Create Ai Agent

Tools to attach to the agent, in the unified simplified shape (the same payload as POST /v1/agents/{agent_id}/tools). This is the preferred way to attach tools — the API resolves catalog ids and wires the graph for you.

Each entry is one of (discriminated on type):

• {"type": "action", "connection_id": "<connection_id>", "operation_ids": ["<catalog_op_id>", ...]}
• {"type": "custom_function", "custom_function_id": "<id>"}
• {"type": "mcp", "mcp_id": "<registry_id>"} OR {"type": "mcp", "url": "https://...", "name": "...", "transport": "...", "auth_type": "...", "allowed_tools": [...]}
• {"type": "agent", "agent_id": "<id>"}
• {"type": "workflow", "workflow_id": "<id>"}
• {"type": "skill", "skill_name": "<name>"}

Resolves into attached_tools + graph server-side, so you don't need to construct those by hand. For advanced control you may still pass attached_tools/graph directly; when both are provided, tools are resolved and merged on top.

Advanced/low-level: list of connector connections with their operation IDs that this agent can use as tools. Prefer tools for the simplified shape. Each entry binds a connection (connector_organization) to specific operations the agent is allowed to invoke.

Structure: [{"id": "<connection_id>", "operation_ids": ["<catalog_operation_id_1>", "<catalog_operation_id_2>"]}]

• 'id' is the connection ID (connector_organization.id) from POST /connectors/{connector_id}/connect
• 'operation_ids' are the catalog operation _id values from GET /connectors/{connector_id}/{connection_id}/operations

If you provide attached_tools without corresponding graph entries, the API will automatically create graph items of type 'tool' for each operation, resolving catalog _id to operationId.

Special cases:

• Custom functions: use id="xpander-custom-functions" and operation_ids=["<custom_function_id>", ...] Custom function IDs are the function UUIDs, not catalog operation IDs.
• Sub-agents: do NOT use attached_tools. Add sub-agents directly to the 'graph' field with type='agent'.
• MCP servers: do NOT use attached_tools. Add MCP servers directly to the 'graph' field with type='mcp'.

Example (connector operations): [{"id": "770832b8-c32b-4e4c-9ca2-232fec8099a7", "operation_ids": ["694bddfcd72d937c39875cf7"]}]

Example (custom functions): [{"id": "xpander-custom-functions", "operation_ids": ["my-function-uuid-1", "my-function-uuid-2"]}]

The agent's tool graph — defines which tools are available to the LLM and their execution flow. Each graph item represents a tool the agent can call during task execution.

For connector operations (type='tool'):

• item_id: the operationId string (e.g., 'XpanderEmailServiceSendEmailWithHtmlOrTextContent')
• name: human-readable name shown to the LLM (e.g., 'Send Email')
• type: 'tool'
• targets: list of graph item IDs that should execute after this tool (empty [] for no chaining)
• NOTE: auto-created from attached_tools if not provided

For sub-agents (type='agent'):

• item_id: the agent ID (UUID) to delegate work to
• name: display name of the sub-agent
• type: 'agent'
• NO attached_tools entry needed — sub-agents are graph-only

For custom functions (type='tool', sub_type='custom_function'):

• item_id: the custom function UUID
• name: function name
• type: 'tool'
• Requires attached_tools entry with id='xpander-custom-functions'

For MCP servers (type='mcp'):

• item_id: a unique ID for this MCP server instance
• name: display name of the MCP server
• type: 'mcp'
• settings.mcp_settings: {url, transport, auth_type, name, allowed_tools, ...}
• NO attached_tools entry needed — MCP servers are graph-only

NOTE: If you provide attached_tools with operation_ids but no corresponding graph items, the API will auto-create graph items with resolved operationId and pretty_name from catalog.

Examples: Connector tool: {"item_id": "SlackPostMessage", "name": "Send Slack Message", "type": "tool", "targets": []} Sub-agent: {"item_id": "agent-uuid-here", "name": "Research Agent", "type": "agent", "targets": []} MCP server: {"item_id": "mcp-uuid", "name": "Notion", "type": "mcp", "targets": [], "settings": {"mcp_settings": {"url": "https://mcp.notion.com/sse", "transport": "sse", "name": "Notion"}}}

Knowledge bases attached to this agent for RAG (Retrieval-Augmented Generation). Each entry references a knowledge base by ID and specifies the retrieval strategy ('vanilla' for simple retrieval, 'agentic_rag' for agent-driven retrieval).

Entry points that can trigger this agent. Defines how the agent can be invoked — via SDK, scheduled tasks, webhooks, assistant UI, MCP, A2A protocol, Telegram, or Slack.

Runtime settings for an agent whose framework is a CLI harness.

Configuration object for task-level execution strategies.

This model groups optional strategy configurations that control how a task is executed and managed over time, including retries, iterative execution, stopping conditions, and daily run limits.

Attributes: retry_strategy: Optional retry policy configuration that defines how the task should behave when execution fails (e.g., max attempts, backoff rules).

iterative_strategy:
    Optional iterative execution configuration for tasks that may run in
    repeated cycles/steps until completion or a stop condition is met.

stop_strategy:
    Optional stopping policy configuration that defines when the task
    should stop running (e.g., timeout, max iterations, success criteria).

max_runs_per_day:
    Optional limit on how many times the task is allowed to run within a
    24-hour period. If not set, no explicit daily limit is enforced.

agentic_context_enabled:
    if agentic memory is enabled and accesible to the executor.

slackbot_formatting_instructions:
    Optional SlackBot formatting instructions

budget:
    Optional spend budgets (agent-period and/or per-task) with thresholds.

Configuration for event-based notifications.

Attributes: on_success: Notifications to send when an operation succeeds. Maps notification types to a list of notification configurations. on_error: Notifications to send when an operation fails. Maps notification types to a list of notification configurations. on_budget: Notifications to send on budget threshold crossings. A dedicated category — budget alerts are not errors.

Workflow orchestration DAG nodes. Only for type=orchestration workflows.

Runtime settings for an agent whose framework is a CLI harness.

Configuration for event-based notifications.

Attributes: on_success: Notifications to send when an operation succeeds. Maps notification types to a list of notification configurations. on_error: Notifications to send when an operation fails. Maps notification types to a list of notification configurations. on_budget: Notifications to send on budget threshold crossings. A dedicated category — budget alerts are not errors.

Configuration object for task-level execution strategies.

This model groups optional strategy configurations that control how a task is executed and managed over time, including retries, iterative execution, stopping conditions, and daily run limits.

Attributes: retry_strategy: Optional retry policy configuration that defines how the task should behave when execution fails (e.g., max attempts, backoff rules).

iterative_strategy:
    Optional iterative execution configuration for tasks that may run in
    repeated cycles/steps until completion or a stop condition is met.

stop_strategy:
    Optional stopping policy configuration that defines when the task
    should stop running (e.g., timeout, max iterations, success criteria).

max_runs_per_day:
    Optional limit on how many times the task is allowed to run within a
    24-hour period. If not set, no explicit daily limit is enforced.

agentic_context_enabled:
    if agentic memory is enabled and accesible to the executor.

slackbot_formatting_instructions:
    Optional SlackBot formatting instructions

budget:
    Optional spend budgets (agent-period and/or per-task) with thresholds.

The person whose Claude or ChatGPT plan serves this agent, whoever starts the turn.

Without it each turn uses the talking person's own pick, so a shared agent runs on whichever plan the last person to message it happened to connect.