Skip to content

Commit 33badeb

Browse files
sinediedsinedied
committed
docs: add agent-cli readme
1 parent 4e959c0 commit 33badeb

File tree

2 files changed

+105
-29
lines changed

2 files changed

+105
-29
lines changed

‎packages/agent-cli/README.md‎

Lines changed: 103 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,51 +1,126 @@
1-
# Contoso Burgers AI lightweight Agent CLI
1+
<div align="center">
22

3-
## Available Scripts
3+
# Agent CLI (LangChain.js)
44

5-
In the project directory, you can run:
5+
![Node version](https://img.shields.io/badge/Node.js->=22-3c873a?style=flat-square)
6+
[![TypeScript](https://img.shields.io/badge/TypeScript-blue?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org)
7+
[![LangChain.js](https://img.shields.io/badge/LangChain.js-1C3C3C?style=flat-square&logo=langchain&logoColor=white)](https://js.langchain.com)
68

7-
### `npm start`
9+
[Overview](#overview) • [Usage](#usage) • [Development](#development) • [Troubleshooting](#troubleshooting)
810

9-
Run the burger agent CLI. Usage examples:
11+
</div>
1012

11-
```bash
12-
# Ask a simple question
13-
npm run start "show me the burger menu"
13+
## Overview
1414

15-
# Ask with a specific user ID
16-
npm run start "place an order" -- --userId user123
15+
The Agent CLI is a minimal command line interface to the same burger ordering LangChain.js agent used by the web experience. It connects directly to the Burger MCP server and uses Azure OpenAI for reasoning. Conversation state is persisted locally in a JSON file so you can build context across multiple invocations.
1716

18-
# Start a new session
19-
npm run start "hello" -- --new
17+
It is useful for:
2018

21-
# Use local MCP server
22-
npm run start "show me the menu" -- --local
19+
- Rapid prototyping / debugging tool calls
20+
- Local experimentation without the web UI
21+
- Understanding LangChain.js agent setup in a simplified context
2322

24-
# Combine options
25-
npm run start "cancel my order" -- --userId user123 --new --local
26-
```
23+
<div align="center">
24+
<img src="../../docs/images/cli-architecture.drawio.png" alt="Architecture" />
25+
</div>
2726

28-
The CLI maintains conversation history in `~/.burger-agent-cli/burger-agent-cli.json` for context across sessions.
27+
## Installation
2928

30-
### Options
29+
Follow the instructions [here](../../README.md#getting-started) to set up the development environment for the entire Burger MCP Agents project.
30+
31+
Then run the following commands from the repository root:
3132

32-
- `--userId <userId>`: Specify a user ID for operations that require user context (like placing or cancelling orders)
33-
- `--new`: Start a new conversation session, discarding previous history
34-
- `--verbose`: Show intermediate steps and tool calls during execution
35-
- `--local`: Force connection to localhost MCP server (http://localhost:3000/mcp) instead of using BURGER_MCP_URL environment variable
33+
```bash
34+
cd packages/agent-cli
35+
npm start "show me a spicy burger"
36+
```
3637

37-
### `npm run build`
38+
You should see a connection message to the Burger MCP server then the streamed assistant answer.
3839

39-
To build the CLI for production to the `dist` folder.
40+
### Global CLI install (optional)
4041

41-
After building, you can install the CLI globally with:
42+
You can build and install the CLI globally to call it directly as `agent-cli`:
4243

4344
```bash
45+
npm run build
4446
npm install -g .
47+
agent-cli "show me a spicy burger"
4548
```
4649

47-
And then run it with:
50+
## Usage
51+
52+
Invoke with a natural language question or instruction about burgers or orders. The agent will refuse unrelated topics.
4853

4954
```bash
50-
agent-cli --help
55+
# Basic menu query
56+
npm start "show me the burger menu"
57+
58+
# Place an order (will ask for userId if missing)
59+
npm start "place an order for 2 classic burgers"
60+
61+
# Provide user id explicitly
62+
npm start "place an order for 1 veggie burger" -- --userId user123
63+
64+
# Cancel an order (new clean session)
65+
npm start "cancel order 42" -- --userId user123 --new
66+
67+
# Force local MCP endpoint (bypass BURGER_MCP_URL)
68+
npm start "what toppings are available" -- --local
69+
70+
# Verbose mode shows intermediate tool steps
71+
npm start "status of my recent orders" -- --userId user123 --verbose
72+
```
73+
74+
> [!TIP]
75+
> If you installed the CLI globally you can replace `npm start` with `agent-cli` and omit the `--` before options.
76+
77+
### Options
78+
79+
| Flag | Description |
80+
|------|-------------|
81+
| `--userId <id>` | Specify the user identity (required for placing or cancelling orders) |
82+
| `--new` | Start a fresh session (ignores prior conversation) |
83+
| `--verbose` | Print intermediate LLM + tool invocation steps |
84+
| `--local` | Force `http://localhost:3000/mcp` instead of `BURGER_MCP_URL` |
85+
| `--help` | Display usage information |
86+
87+
### Conversation history
88+
89+
Session data (messages + last used userId) is stored at:
90+
5191
```
92+
~/.burger-agent-cli/burger-agent-cli.json
93+
```
94+
95+
Delete that file or use `--new` to reset context.
96+
97+
### Environment Variables
98+
99+
| Variable | Required | Purpose | Default |
100+
|----------|----------|---------|---------|
101+
| `AZURE_OPENAI_API_ENDPOINT` | Yes | Azure OpenAI endpoint used for chat completions | – |
102+
| `AZURE_OPENAI_MODEL` | No | Model name for the LLM | `gpt-5-mini` |
103+
| `BURGER_MCP_URL` | No* | Streamable HTTP MCP endpoint | `http://localhost:3000/mcp` |
104+
| `AGENT_WEBAPP_URL` | No | Used in prompt to guide users where to retrieve their user ID | `http://localhost:4280` |
105+
106+
<sup>*</sup>When not set the CLI falls back to the local development endpoint. Set this when targeting a deployed MCP server.
107+
108+
Authentication to Azure OpenAI uses `DefaultAzureCredential`. Ensure you are logged in by running either `azd auth login` or `az login`.
109+
110+
## Development
111+
112+
### Available Scripts
113+
114+
| Script | Description |
115+
|--------|-------------|
116+
| `npm start` | Build then run a single agent interaction |
117+
| `npm run build` | Compile TypeScript to `dist` |
118+
| `npm run watch` | Incremental compile in watch mode |
119+
| `npm run clean` | Remove build artifacts |
120+
121+
## Troubleshooting
122+
123+
- Missing `AZURE_OPENAI_API_ENDPOINT`: set it in the root `.env` or export it in your shell
124+
- Repeated auth failures: re-run `az login` or clear cached Azure credential tokens
125+
- MCP connection issues: ensure the MCP server is running and `BURGER_MCP_URL` is correct
126+

‎packages/agent-cli/package.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,8 @@
88
"agent-cli": "./bin/cli.js"
99
},
1010
"scripts": {
11-
"start": "npm run build -s && ./bin/cli.js --",
11+
"start": "./bin/cli.js --",
12+
"prestart": "tsc",
1213
"build": "tsc",
1314
"watch": "tsc -w",
1415
"clean": "rimraf dist"

0 commit comments

Comments
 (0)