The agent object

⚠️

Preview — this feature is being built; the design below is the spec.

The agent object as the API returns it. Every field below appears in every response that returns this object; fields with no value are null rather than missing.

Example

{
  "id": "agt_01JC4R8W6Q2N9X3T5V7Y",
  "type": "agent",
  "name": "refund-desk",
  "description": "Handles refund requests from the support inbox.",
  "version": 4,
  "status": "active",
  "model": "Amara S1.2",
  "instructions": "You handle refund requests for Acme Store. Look the order up before answering.",
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "lookup_order",
        "description": "Fetch an order by its id.",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": {
              "type": "string"
            }
          },
          "required": [
            "order_id"
          ]
        }
      }
    }
  ],
  "tool_policy": {
    "default": "allow",
    "require_approval": [
      "issue_refund"
    ]
  },
  "mcp_servers": [],
  "skills": [],
  "environment_id": null,
  "memory_store_ids": [],
  "vault_ids": [],
  "limits": {
    "max_turns": 30,
    "max_output_tokens_per_turn": 4096,
    "session_token_budget": 400000,
    "session_cost_budget_usd": 2.0
  },
  "metadata": {
    "team": "support"
  },
  "created_at": "2026-11-03T09:14:22Z",
  "updated_at": "2026-11-05T16:02:10Z"
}

Fields

Field	Type	Description
`id`	string	Starts with `agt_`; the same across versions.
`type`	string	The object type, always `agent`.
`name`	string	Unique in the workspace: 1 to 64 lowercase letters, digits, `-` and `_`.
`description`	string	Free-text description.
`version`	integer	The version this object describes, from `1`.
`status`	string	`active` or `archived`.
`model`	string	A Syntic model name. Unknown names are rejected; there is no fallback here.
`instructions`	string	System instructions, up to 100,000 characters.
`tools`	array	Function tools and built-in tool entries, up to 128.
`tool_policy`	object	`default` (`allow` or `ask`) plus `require_approval` and `deny` lists of tool names.
`mcp_servers`	array	Remote MCP servers; tokens come from a vault by name.
`skills`	array	`{skill_id, version}` entries.
`environment_id`	string or null	Where code tools run; `null` means no code execution.
`memory_store_ids`	array	Memory stores the agent may use.
`vault_ids`	array	Vaults whose secrets tools may use.
`limits`	object	Defaults for every session: `max_turns`, `max_output_tokens_per_turn`, `session_token_budget`, `session_cost_budget_usd`.
`metadata`	object	Up to 16 string pairs.
`created_at`	string	When it was created, RFC 3339 UTC (some older objects use Unix seconds).
`updated_at`	string	When it last changed.

Returned by

admin_key agent_execution

Was this page helpful?