Agents and configuration
Console agents in the ai_agents table, the config the server sends with each segment, the environment on both sides and a local run of the agent.
The server is the only place an agent’s configuration lives. The agent keeps no copy: each segment gets it in the agent_config field of POST /runs.
Agents in ai_agents
The server’s ai_agents table holds two kinds of agent. Migration 0056 seeds the first rows.
| Kind | Seeded agents | Used by | Admins can |
|---|---|---|---|
console | Console assistant (console-agent) | moderators, picked in the ask box | create, edit, turn on and off |
app | Scam check, Listing photo reader, Search, Search embeddings | the server’s code | change the model, limits and budget |
An agent has a display name (“Console assistant”) and an alias (console-agent) used only on calls to LiteLLM. Each save of new instructions adds a version to ai_agent_versions with who saved it and when. A question that names no agent uses the Console assistant; an unknown agent or an app agent is 404 ai_agent_not_found, and one turned off is 409 ai_agent_disabled.
Admins manage agents, models, providers and budgets under Settings in the console. The server writes those changes to LiteLLM through its admin API.
Config per segment
"agent_config": {
"id": "uuid", "name": "Console assistant",
"alias": "console-agent", // model alias in LiteLLM
"instructions": "…", "instructions_version": 3,
"tools": ["ticket_get", "account_get"], // MCP tools the agent may use
"limits": { "deadline_s": 60, "max_model_calls": 40, "context_window": 128000,
"tool_timeout_s": 20, "tool_attempts": 3, "max_tokens": 4096 }
}The agent drops unknown keys; a value out of range refuses the whole request with 400. A segment’s system prompt is the built-in prompt (role, the open record, the moderation and support rules), the output tool rules, the agent’s instructions and the skill’s prompt when the question uses one.
Environment
Values shared by compose and every stack live in infra/stack/env/agent.env; the chart reads that file and compose reads it through env_file. The two tokens and the LiteLLM key are in the keys volume’s .env.
| Variable | Side | Meaning |
|---|---|---|
AGENT_BASE_URL | server | The agent’s internal address, such as http://agent-dev:3000 |
AGENT_SERVICE_TOKEN | both | Token the server sends with POST /runs; empty refuses every request |
AGENT_MCP_ADDR | server | The MCP server’s listener, 0.0.0.0:9090 |
AGENT_MCP_TOKEN | both | Token the agent sends to MCP and the control endpoint |
MCP_SERVER_URL | agent | The server’s /mcp, such as http://server-dev:9090/mcp; its origin also serves the control endpoint |
AGENT_MODEL_ID | agent | Alias used when agent_config has none, console-agent |
LITELLM_BASE_URL, LITELLM_API_KEY | agent | LiteLLM’s OpenAI-compatible endpoint and key |
LITELLM_URL, LITELLM_MASTER_KEY | server | LiteLLM’s admin API, for the Settings pages |
AGENT_TURN_DEADLINE_MS | agent | A segment’s default deadline, 60 000 |
FEATURE_ALL_AGENT, FEATURE_LLM | agent | false refuses every segment with 503 |
Each token has at least 32 characters; the server’s cmd/envgen writes both. No log line carries a token or the master key. The agent’s full list is in agent/.env.example and agent/src/config.ts.
A local run
The agent has no compose file of its own. It runs on the stack’s LiteLLM and MCP, from the umbrella repo’s docker-compose.yml or the cluster.
cd agent
npm install
cp .env.example .env
# Set AGENT_SERVICE_TOKEN, AGENT_MCP_TOKEN, MCP_SERVER_URL and LiteLLM to the stack's.
npm run start:dev
npm run chat -- "Có bao nhiêu ticket đang mở?"npm run chat posts one new segment to the agent on PORT as CLI_MEMBER_ID and prints its events and end line. It calls the real model and MCP, which may cost money. Without the server’s control endpoint the polls fail and the segment goes on without Pause, Stop now or updates.
Tests
npm run build
npm run typecheck
npm test # offline
npm run test:live-cache # calls a real LiteLLM; skipped without LIVE_LITELLM_URL and LIVE_LITELLM_KEYnpm test uses a scripted model, a fake server on 127.0.0.1 (an MCP server with read-only and write tools, and the control endpoint) and an in-memory line collector. The suites cover the token, the 400 and 503 refusals, NDJSON framing, steps, source numbers, documents, tool retry, ask_user, pause and resume, updates while running, Stop now, the budget, the deadline and context compaction.