Skip to main content

​
Installation

pip install agent-engine
agentctl --help
Global flag available on every command: 
agentctl --log-level DEBUG|INFO|WARNING|ERROR <command>

​
Commands

​
validate

Check a spec file offline — no LLM calls, no network, no MCP connections. 
agentctl validate agents.yml
Checks schema, all references (tools, resolvers, MCPs), prompt file paths, graph structure, and imports any declared hooks to verify they load. Exits non-zero on any error.

​
inspect

Print a summary of the spec — agents, orchestrators, MCP servers, hooks, and tool tags — without running anything. 
agentctl inspect agents.yml
Hook config is shown as key names only, never values. MCP tool tags and transport type are shown per server.

​
generate

Create plugin stubs from the spec. Safe to run repeatedly — existing implementations are preserved by default. 
agentctl generate agents.yml                          # all stubs
agentctl generate agents.yml --mode all               # regenerate everything
agentctl generate agents.yml --mode children          # agent resolver files only
agentctl generate agents.yml --mode child --agent orders_agent  # one agent
agentctl generate agents.yml --force                  # overwrite existing files
Generates:
  • plugins/resolvers/shared.py — SharedResolver with shared methods
  • plugins/resolvers/<agent_id>.py — per-agent Resolver subclass
  • plugins/tools/<tool_id>.py — tool stubs
  • plugins/hooks/<hook_id>.py — hook stubs
  • plugins/plugins.toml — plugin manifest

​
run

Send one message through the engine. Persists the conversation via agent_manager. 
agentctl run --config agents.yml --message "Where is my order?"
agentctl run --config agents.yml --message "Where is my order?" --stream
agentctl run --config agents.yml --message "..." --session-id abc123
agentctl run --config agents.yml --message "..." --user-id user-456
agentctl run --config agents.yml --message "..." --env .env
FlagDescription
--configPath to the spec file
--messageThe user message
--streamPrint tokens as they arrive
--session-idAttach to an existing session
--user-idAssociate with a user
--envLoad environment variables from a file

​
serve

Start the stateless engine HTTP API. No persistence, no widget. 
agentctl serve --config agents.yml
agentctl serve --config agents.yml --host 0.0.0.0 --port 8080
agentctl serve --config agents.yml --env .env
Endpoints: GET /health, POST /invoke, POST /stream Default port: 8090. Override it with --port or the PORT env var (e.g. PORT=8080 agentctl serve --config agents.yml).

​
chat

Interactive developer console. Keeps one engine alive, lets you ask multiple questions without restarting. Nothing is persisted. 
# Local engine
agentctl chat --config agents.yml
agentctl chat --config agents.yml --stream

# Against a running agentctl serve
agentctl chat --url http://localhost:8090
agentctl chat --url http://localhost:8090 --stream
Pass --config (local) or --url (remote), not both. Type exit, quit, or press Ctrl-C to stop.

​
agent-manager

Separate command for the conversation layer + widget: 
agent-manager --config agents.yml
agent-manager --config agents.yml --host 0.0.0.0 --port 8100
agent-manager --config agents.yml --env .env
Default port: 8100 Endpoints: POST /conversations, GET /conversations/{id}/messages, POST /conversations/{id}/messages, POST /conversations/{id}/messages/stream, GET /widget.js