Extending

Tasks: the work order.

A task is a structured, parameterized execution: defined in a markdown file, run headless through the normal agent runtime, required to return valid JSON. Tasks are how software — scripts, notebooks, MCP clients, even other agents — gets reliable results out of GoTo Agents without a conversation.

Defined in TASK_*.md

---
type: task
parameters:
  user_instructions:
    required: true
    description: Task instructions in natural language
skills: []
mcp_servers: []
---
Complete this task: {{ user_instructions }}

## Output Format
Return JSON with fields appropriate for the task.

The body is a Jinja2 template rendered with the declared parameters (extras arrive as additional_params). Required parameters are validated before anything runs. TASK_default.md handles generic instructions; TASK_<id>.md defines named tasks.

Scopes and overrides

Global defaults seed new workspaces; workspace tasks live at the workspace root; agent tasks live in the agent's folder and override workspace tasks with the same id (a disabled agent task blocks fallback). Workspace-level tasks run on a dedicated internal Task Bot agent that doesn't appear as a chat target.

The JSON contract

Task runs create real sessions (session_type='task') with the full model/tool/skill/MCP stack — an executing task can read project files, use skills, and call MCP tools. What makes it a task is the exit condition: output must be valid JSON, and malformed output triggers automatic correction retries before failing. Errors come back structured: {"error": "...", "needs_human": true}. Every run persists an execution record with history, and runs can be resumed by session id — a task that needed human input can pick up where it stopped.

Four ways to run one

  • UI — run and inspect executions from the workspace.
  • HTTP — task run, resume, history, and definition endpoints.
  • Python — GTAClient from scripts and notebooks. See Python Client.
  • MCP — gta_run_task / gta_resume_task from any MCP client. See GTA as MCP Server.

Agents can also invoke tasks conversationally via the built-in run_task tool — a chat agent delegating a structured work order and using the JSON result.

Where it lives

  • core/task_manager.py — discovery, parsing, Jinja2 rendering.
  • core/task_execution_manager.py — sessions, execution records, retries, resume.
  • core/json_output_validator.py — the JSON contract and correction prompts.
  • core/run_task_tool.py — the in-conversation tool.