Skip to main content
The agentservice CLI is developed in the cli/ directory of the agents-api monorepo (sibling to this docs repo as ../cli/). PyPI / wheel package name: agentservice. Console script: agentservice.

​
Install

From a built wheel (version in the filename may differ):
The wheel vendors the agentsapi client and pulls runtime dependencies (httpx, pydantic, etc.).

​
Optional: tab completion

Add the eval line to ~/.bashrc or ~/.zshrc to persist (on zsh, load bash completion compatibility first).

​
Configure

You will be prompted for an API key (create one under Sudoiq settings). Default API host:
Environment variable AGENTSERVICE_API_KEY, flag --api-key, or config files ~/.config/agentservice/config / ~/.agentservice (api_key=..., host=...) are also supported. --base-url overrides the host for a single command.

​
Agents (workflows)

Use agentservice agents modify --help for the full surface: inspect or edit the graph with list, show-node, list-edges, set-node, set-edges, patch-edges, or an interactive shell. Backward compatibility: older one-liners are still rewritten internally—agentservice agents modify <AGENT_ID> behaves like pull, and --submit / --discard on that form map to submit / discard.

​
Execute and wait

--wait follows the run until a terminal state. The implementation prefers server push (SSE) when the bundled client supports it and falls back to periodic HTTP checks if streaming is unavailable (see agentservice execute --help). Task inspection:
With --tool-handler, local tool execution uses your script (see demo below); that path may use polling as documented in the CLI help.

​
Tools and validators

​
Add a tool from JSON

Create tools.json with the same shape the API expects, then push:
Wire local execution for tool calls with agentservice task status --wait --tool-handler "python your_module.py" or use the Python client’s set_tools for streaming runs (see Python client).

​
Push / list

Push JSON from a file or stdin:
Export current definitions (push-compatible JSON):
Expected shapes: { "tools": [ { "name", "namespace", "description", "schema_data" }, ... ] } and { "validators": [ { "name", "json_schema" }, ... ] }.

​
Demo generator

Generates a sample tool + validator module and prints steps to push definitions and run with a tool handler.