v2

OpenAPI 3.0.02026-08-051996591.2 MB
Agents

List agents

Lists all agents available to the authenticated user. Results are paginated.

get/v2/agents

Query parameters

filterstring
Example:support.*

A regular expression against agent names and descriptions to filter the results.

enabledboolean
Example:true

Filter agents by enabled status.

limitinteger

The maximum number of agents to return in the list.

page_keystring

The opaque cursor returned in metadata.page_key of the previous response. Omit it to fetch the first page.

Headers

Request-Timeoutinteger

The platform makes a best effort to complete the request in the specified seconds, or it times out.

Request-Timeout-Millisinteger

The platform makes a best effort to complete the request in the specified milliseconds, or it times out.

Response

List of available agents.

Example response

{
  "agents": [
    {
      "key": "customer_support",
      "name": "Customer Support Agent",
      "description": "An AI agent specialized in handling customer support inquiries using company documentation and support tools.",
      "tool_configurations": {
        "customer_search": {
          "type": "corpora_search",
          "argument_override": {
            "query": "customer support documentation"
          }
        }
      },
      "skills": {
        "code_review": {
          "description": "Reviews code for best practices and security issues.",
          "content": "When reviewing code, focus on..."
        }
      },
      "model": {
        "name": "gpt-4",
        "parameters": {
          "temperature": 0.7,
          "max_tokens": 1000,
          "top_p": 0.9
        },
        "retry_configuration": {
          "enabled": true,
          "max_retries": 3,
          "initial_backoff_ms": 1000,
          "max_backoff_ms": 30000,
          "backoff_factor": 2
        }
      },
      "first_step": {
        "name": "classifier",
        "instructions": [
          {
            "id": "ins_customer_support_init",
            "version": 1
          }
        ],
        "output_parser": {
          "type": "default"
        },
        "reminders": [
          {
            "type": "templated",
            "template_type": "velocity",
            "template": "You are an expert customer support agent for $agent.name. Available tools: #foreach($tool in $tools)${tool.name}#if($foreach.hasNext), #end#end",
            "hooks": [
              "tool_output"
            ],
            "fire_every": 3,
            "skip_first": 2
          }
        ],
        "next_steps": [
          {
            "condition": "get('$.output.intent') == 'sales'",
            "step_name": "sales_handler"
          }
        ],
        "allowed_tools": [
          "customer_search",
          "web_search"
        ],
        "allowed_skills": [
          "code_review",
          "debugging"
        ],
        "reentry_step": "classifier"
      },
      "first_step_name": "classifier",
      "steps": {
        "sales_handler": {
          "instructions": [
            {
              "type": "inline",
              "template": "Handle sales inquiries"
            }
          ],
          "output_parser": {
            "type": "default"
          }
        },
        "support_handler": {
          "instructions": [
            {
              "type": "inline",
              "template": "Handle support requests"
            }
          ],
          "output_parser": {
            "type": "default"
          }
        }
      },
      "metadata": {
        "department": "customer_service",
        "version": "1.2.0",
        "owner": "support-team"
      },
      "enabled": true,
      "compaction": {
        "enabled": true,
        "threshold_percent": 80,
        "keep_recent_inputs": 1
      },
      "tool_output_offloading": {
        "enabled": true,
        "mode": "artifact",
        "context_percentage": 0.25,
        "max_threshold_bytes": 1048576,
        "min_threshold_bytes": 4096,
        "headroom_percentage": 0.7
      },
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-16T14:45:00Z"
    }
  ],
  "metadata": {
    "page_key": "eyJvZmZzZXQiOjF9"
  }
}