Extending

The Python client: GoTo Agents from code.

The gotoagents package is the public Python client for a running GoTo Agents server — for scripts, notebooks, automation, and adapters (the MCP connector is built on it). It's a remote client: it talks to the server's API and never loads workspace files or runs agents in-process, so client code and server state can't drift apart.

Install and connect

# from a cloned checkout
python -m pip install -e .

# server must be running
python start.py
from gotoagents import GTAClient

gta = GTAClient(
    url="http://localhost:8000",
    timeout=60,
    workspace_name="song-studio",   # optional client-side defaults
    profile="stacey",
    project_folder="C:/music/ep-2026",
)

Defaults are client-side conveniences — every call that needs context either uses values set on the client or takes them explicitly. A bare client with just a URL works fine for discovery calls.

What you do with it

  • Run tasks — the primary use: invoke TASK_*.md definitions with parameters, get validated JSON back, resume interrupted runs, page through execution history. See Tasks.
  • Discover — list profiles, workspaces, task definitions, and recent project folders to drive dynamic integrations.
  • Converse — create sessions and exchange messages with agents from code, notebook-style.

Notebooks

The client is deliberately notebook-friendly: synchronous calls, plain dict results, a requests.Session escape hatch for custom transport. Install into the active kernel with !{sys.executable} -m pip install -e "path/to/goto-agents".

Where it lives

  • gotoagents/client.py — the client itself.
  • help/python-client.md in the repo — the full argument-level reference.
  • examples/ — usage examples.