Skip to main content
The Agent API provides endpoints for controlling the agent lifecycle, managing extensions, and interacting with tools.

​
Start Agent

Create a new agent session. 
POST /agent/start

​
Request Body

{
  "working_dir": "/path/to/project",
  "recipe": {
    "name": "my-task",
    "instructions": "Help with coding"
  },
  "recipe_id": "recipe-123",
  "recipe_deeplink": "goose://...",
  "extension_overrides": [
    {
      "name": "filesystem",
      "type": "builtin",
      "description": "File operations"
    }
  ]
}

​
Response

Returns a Session object: 
{
  "id": "session-abc123",
  "name": "New Chat",
  "working_dir": "/path/to/project",
  "created_at": "2026-03-04T10:00:00Z",
  "updated_at": "2026-03-04T10:00:00Z"
}

​
Example

curl -X POST http://localhost:8080/agent/start \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "working_dir": "/home/user/project"
  }'

​
Resume Agent

Resume an existing agent session and load its model/extensions. 
POST /agent/resume

​
Request Body

{
  "session_id": "session-abc123",
  "load_model_and_extensions": true
}

​
Response

{
  "session": {
    "id": "session-abc123",
    "name": "My Chat"
  },
  "extension_results": [
    {
      "name": "filesystem",
      "success": true
    }
  ]
}

​
Example

curl -X POST http://localhost:8080/agent/resume \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "session-abc123",
    "load_model_and_extensions": true
  }'

​
Stop Agent

Stop a running agent and clean up resources. 
POST /agent/stop

​
Request Body

{
  "session_id": "session-abc123"
}

​
Example

curl -X POST http://localhost:8080/agent/stop \
  -H "Content-Type: application/json" \
  -d '{"session_id": "session-abc123"}'

​
Restart Agent

Restart an agent, reloading its configuration and extensions. 
POST /agent/restart

​
Request Body

{
  "session_id": "session-abc123"
}

​
Response

{
  "extension_results": [
    {
      "name": "filesystem",
      "success": true
    }
  ]
}

​
Update Provider

Change the AI model provider for an agent. 
POST /agent/update_provider

​
Request Body

{
  "session_id": "session-abc123",
  "provider": "openai",
  "model": "gpt-4",
  "context_limit": 128000,
  "request_params": {
    "temperature": 0.7
  }
}

​
Example

curl -X POST http://localhost:8080/agent/update_provider \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "session-abc123",
    "provider": "anthropic",
    "model": "claude-3-5-sonnet-20241022"
  }'

​
Update Working Directory

Change the agent’s working directory. 
POST /agent/update_working_dir

​
Request Body

{
  "session_id": "session-abc123",
  "working_dir": "/new/path"
}

​
List Tools

Get all available tools for a session. 
GET /agent/tools?session_id={session_id}&extension_name={name}

​
Query Parameters

  • session_id (required): Session identifier
  • extension_name (optional): Filter tools by extension

​
Response

[
  {
    "name": "read_file",
    "description": "Read contents of a file",
    "parameters": ["path"],
    "permission": "allowed"
  }
]

​
Example

curl "http://localhost:8080/agent/tools?session_id=session-abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Call Tool

Directly call a tool (useful for UI integrations). 
POST /agent/call_tool

​
Request Body

{
  "session_id": "session-abc123",
  "name": "read_file",
  "arguments": {
    "path": "/home/user/file.txt"
  }
}

​
Response

{
  "content": [
    {
      "type": "text",
      "text": "File contents here..."
    }
  ],
  "is_error": false
}

​
Example

curl -X POST http://localhost:8080/agent/call_tool \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "session-abc123",
    "name": "read_file",
    "arguments": {"path": "README.md"}
  }'

​
Read Resource

Read a resource from an MCP server. 
POST /agent/read_resource

​
Request Body

{
  "session_id": "session-abc123",
  "extension_name": "filesystem",
  "uri": "file:///path/to/file"
}

​
Response

{
  "uri": "file:///path/to/file",
  "mime_type": "text/plain",
  "text": "Resource contents..."
}

​
Add Extension

Dynamically add an extension to a running agent. 
POST /agent/add_extension

​
Request Body

{
  "session_id": "session-abc123",
  "config": {
    "name": "github",
    "type": "stdio",
    "description": "GitHub integration",
    "cmd": "mcp-server-github",
    "args": []
  }
}

​
Example

curl -X POST http://localhost:8080/agent/add_extension \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "session-abc123",
    "config": {
      "name": "memory",
      "type": "builtin",
      "description": "Memory management"
    }
  }'

​
Remove Extension

Remove an extension from a running agent. 
POST /agent/remove_extension

​
Request Body

{
  "session_id": "session-abc123",
  "name": "github"
}

​
Example

curl -X POST http://localhost:8080/agent/remove_extension \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "session-abc123",
    "name": "memory"
  }'

​
List Apps

Get available MCP apps from loaded extensions. 
GET /agent/list_apps?session_id={session_id}

​
Response

{
  "apps": [
    {
      "resource": {
        "name": "my-app",
        "uri": "ui://apps/my-app"
      },
      "mcp_servers": ["server-1"]
    }
  ]
}

​
Export App

Export an MCP app as HTML. 
GET /agent/export_app/{name}

​
Response

Returns HTML string of the app.

​
Import App

Import an MCP app from HTML. 
POST /agent/import_app

​
Request Body

{
  "html": "<html>...</html>"
}

​
Response

{
  "name": "imported-app",
  "message": "App 'imported-app' imported successfully"
}

​
Error Responses

All endpoints may return these error codes:
CodeDescription
400Bad request - invalid parameters
401Unauthorized - invalid API key
404Resource not found
424Failed Dependency - agent not initialized
500Internal server error

​
Error Response Format

{
  "message": "Agent not initialized"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us