Вектор Решений Agent OS
Live demos

Quick Start

🔵 Goal — get Agent OS running in a couple of minutes and see a working agent: open the widget and chat with hello-agent — the demo agent from the starter config.

2.1 Launch

You need the compiled agent-os binary (a single CLI, subcommand serve) and the config/ tree. The distribution (download) has both: the binaries are in bin/, the starter config is in config/.

The server is launched from the root of the unpacked archive — config/ and .env are looked up relative to the current folder, not next to the binary:

agent-os-distrib/        ← launch from here
├── bin/agent-os
├── config/
├── .env.example
└── .env                 ← you create this

The API key goes into .env — secrets only there, not in YAML:

cp .env.example .env        # Windows: copy .env.example .env

Open .env and put your key into DEEPSEEK_API_KEY (also works with AGENT_OS_API_KEY). The remaining lines in the template are commented out — no need to touch them. The key is optional: without it the server still starts, and agents respond with simulated answers (a warning will appear in the log).

Then launch:

./bin/agent-os serve        # Windows: bin\agent-os.exe serve

The server comes up on 127.0.0.1:3000. A different address — via a variable (in .env or in the environment):

AGENT_OS_BIND=0.0.0.0:8080 ./bin/agent-os serve

Check that the server is alive and which agents are loaded:

curl http://127.0.0.1:3000/health

The templates field should contain hello-agent and mcp-demo-agent.

2.2 See the agent right away

Open in your browser:

http://127.0.0.1:3000/widget?model=hello-agent

This is the widget page, already connected to the hello-agent agent — you can type in the chat. Ask it to count words or characters in a text: it will call its text_stats tool (a JavaScript script from config/agents/hello/tools/).

In ?model= you specify the template name — the name: field from agent.yaml (hello-agent), not the folder name (hello).

The second demo agent, mcp-demo-agent, reads files through an external MCP server and requires Node.js to be installed (npx in PATH); without Node it will load, but the tool call will return an error.

Other ready-made pages:

URL What it is
/widget?model=hello-agent widget with a specific agent
/demo widget demo
/demo/overlay widget over live sites (tabs from config/demo.yaml)
/site/ markdown site from config/web/
/sessions, /dashboard admin panels (sessions, system state)
/v1/templates list of available agent templates

The starter config has neither config/web/ nor config/demo.yaml, so /site/ returns 404, and /demo/overlay has no tabs — until you add them. The site is described in 13-web-content; the overlay tabs are set in config/demo.yaml (tabs: [{label, url, model}], hot-reloads on the fly).

2.3 Provider — not just DeepSeek

The model is set in config/server.yaml in the provider block. By default it's DeepSeek, but any OpenAI-compatible API and local models will work:

provider:
  base_url: "https://api.deepseek.com"
  model: "deepseek-chat"
  api_key: ""            # пусто → ключ берётся из .env

Examples:

The provider's address and model are set only here; any provider's key goes into .env as AGENT_OS_API_KEY (or DEEPSEEK_API_KEY). Variables like OPENAI_API_KEY, OPENAI_BASE_URL, and AGENT_OS_MODEL are not read by the server.

Several models at once — via named models: configs; the agent template selects the one it needs with the model: field in its agent.yaml.

2.4 Chat via the API

For integration, the same conversation is available through the chat endpoint (SSE stream):

curl http://127.0.0.1:3000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"hello-agent","messages":[{"role":"user","content":"Привет!"}]}'

Here model is the agent template name. The full request and event format is in 08-http-api.

2.5 Embed the widget

On any page of a site:

<script src="http://127.0.0.1:3000/widget.js"></script>

2.6 Where to go next