Skip to main content
The agentservice CLI is developed in the cli/ directory of the Agent Service 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): 
pip install agentservice-0.1.1-py3-none-any.whl
The wheel vendors the asapi client and pulls runtime dependencies (httpx, pydantic, etc.).

​
Optional: tab completion

pip install "agentservice[completion]"
eval "$(register-python-argcomplete agentservice)"
Add the eval line to ~/.bashrc or ~/.zshrc to persist (on zsh, load bash completion compatibility first).

​
Configure

agentservice login
You will be prompted for an API key (create one under Sudoiq settings). Default API host: 
agentservice config --host sudoiq.com
# or a full URL, e.g. https://api.example.com
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)

agentservice agents list
agentservice agents create --name "My Agent"
agentservice agents modify pull <AGENT_ID>          # draft under .agentservice/modify/<ID>/workflow.yml
agentservice agents modify validate [--agent-id <AGENT_ID>]   # client-side checks before submit (ID optional if only one draft)
agentservice agents modify submit <AGENT_ID>        # publish draft as a new version (aliases: commit)
agentservice agents modify discard <AGENT_ID>       # drop local draft without publishing (aliases: trash)
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

agentservice execute --agent-id AGENT_ID --input 1="Hello"
agentservice execute --agent-id AGENT_ID --agent-version 3 --input 1="Hello"
agentservice execute --agent-id AGENT_ID --input 1="Hello" --wait
agentservice execute-with-file --agent-id AGENT_ID -f file.pdf
--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: 
agentservice task status --task-id TASK_ID --agent-id AGENT_ID
agentservice task status --task-id TASK_ID --agent-id AGENT_ID --wait
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: 
{
  "tools": [
    {
      "name": "get_current_time",
      "namespace": "main",
      "description": "Return the current UTC time as ISO 8601.",
      "schema_data": {
        "type": "object",
        "properties": {},
        "required": []
      }
    }
  ]
}

agentservice tools push -f tools.json
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: 
agentservice tools push -f tools.json
agentservice validators push -f validators.json
Export current definitions (push-compatible JSON): 
agentservice tools list > tools.json
agentservice validators list > validators.json
Expected shapes: { "tools": [ { "name", "namespace", "description", "schema_data" }, ... ] } and { "validators": [ { "name", "json_schema" }, ... ] }.

​
Demo generator

agentservice demo
agentservice demo -o my_demo.py
Generates a sample tool + validator module and prints steps to push definitions and run with a tool handler.