Skip to content
ShopNexus Docs
On this page Agents in ai_agents 1/5

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.

KindSeeded agentsUsed byAdmins can
consoleConsole assistant (console-agent)moderators, picked in the ask boxcreate, edit, turn on and off
appScam check, Listing photo reader, Search, Search embeddingsthe server’s codechange 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.

VariableSideMeaning
AGENT_BASE_URLserverThe agent’s internal address, such as http://agent-dev:3000
AGENT_SERVICE_TOKENbothToken the server sends with POST /runs; empty refuses every request
AGENT_MCP_ADDRserverThe MCP server’s listener, 0.0.0.0:9090
AGENT_MCP_TOKENbothToken the agent sends to MCP and the control endpoint
MCP_SERVER_URLagentThe server’s /mcp, such as http://server-dev:9090/mcp; its origin also serves the control endpoint
AGENT_MODEL_IDagentAlias used when agent_config has none, console-agent
LITELLM_BASE_URL, LITELLM_API_KEYagentLiteLLM’s OpenAI-compatible endpoint and key
LITELLM_URL, LITELLM_MASTER_KEYserverLiteLLM’s admin API, for the Settings pages
AGENT_TURN_DEADLINE_MSagentA segment’s default deadline, 60 000
FEATURE_ALL_AGENT, FEATURE_LLMagentfalse 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_KEY

npm 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.

ShopNexus Docs
EN VI