---
title: "Update Ai Agent"
method: PATCH
path: "/v1/agents/{agent_id}"
tags: ["API v1", "Agents", "Agents CRUD"]
---

# Update Ai Agent

`PATCH /v1/agents/{agent_id}`

## Request

- Base URL: `https://api.xpander.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.xpander.ai/v1/agents/{agent_id}`
- Auth: API key in header `x-api-key`

Update an existing AI agent's configuration, tools, or knowledge bases. Use deploy=true to apply changes immediately.

## Path parameters

- `agent_id` string, required

## Query parameters

- `deploy` boolean: Automatically deploy the agent after updating to apply changes immediately. Without this, changes are staged but not active until a PUT deploy call.

## Request body

- UpdateAgentRequest: Request model for updating an existing AI agent. All fields are optional — only provide the fields you want to change. At least one field must be provided. Fields not included in the request will retain their current values. System-managed fields like `organization_id`, `agent_id`, `id`, `status`, `version`, etc. are set by the service layer and should not be provided.
  - `default_user_id` string, nullable: Fallback organization user for unattended executions; also used for user budgets and usage attribution.
  - `background_user_overrides` object, nullable
  - `organization_id` string, nullable: Set automatically by the API service from the authenticated request.
  - `agent_id` string, nullable: Set automatically by the API service from the URL path parameter.
  - `name` string, nullable: Human-readable name for the agent.
  - `description` string, nullable: A brief description of what the agent does.
  - `icon` string, nullable: Emoji icon displayed next to the agent name.
  - `avatar` string, nullable: Avatar identifier for the agent's visual representation.
  - `type` 'manager' | 'regular' | 'a2a' | 'curl' | 'orchestration': Enumeration of the agent types. Attributes: Manager: marks the agent as a Managing agent. Regular: marks the agent as a regular agent. A2A: marks the agent as an external agent used via A2A protocol. Curl: marks the agent as an external agent used via a CURL. Orchestration: marks the agent as an Orchestration object.
  - `status` 'DRAFT' | 'ACTIVE' | 'INACTIVE': Enumeration of possible agent statuses. Attributes: DRAFT: Agent is in a draft state. ACTIVE: Agent is active and operational. INACTIVE: Agent is inactive and not operational.
  - `model_provider` union: The LLM provider to use: a built-in provider or the slug of a custom provider registered for your organization.
    - 'openai' | 'nim' | 'amazon_bedrock' | 'azure_ai_foundary' | 'huggingFace' | 'friendlyAI' | 'anthropic' | 'gemini' | 'fireworks' | 'google_ai_studio' | 'helicone' | 'bytedance' | 'tzafon_lightcone' | 'cerebras' | 'open_router' | 'nebius' | 'cloudflare_ai_gw' | 'z_ai'
    - string
  - `model_name` string, nullable: The specific model identifier.
  - `llm_reasoning_effort` 'low' | 'medium' | 'high' | 'xhigh'
  - `llm_api_base` string, nullable: Custom API base URL for the LLM provider.
  - `llm_credentials_key` string, nullable: Reference key to stored LLM API credentials.
  - `llm_credentials_key_type` 'xpander' | 'custom'
  - `llm_credentials` LLMCredentials
    - `name` string, required
    - `description` string, nullable
    - `value` string, required
  - `llm_extra_headers` object, nullable: Additional HTTP headers for LLM requests.
  - `instructions` AIAgentInstructions
    - `role` string[], nullable
    - `goal` string[], nullable
    - `general` string, nullable
    - `dynamic_prompt_enabled` boolean, nullable
    - `dynamic_prompt_code` string, nullable
    - `dynamic_prompt_position` 'before' | 'after', nullable
  - `expected_output` string, nullable: Description of expected output format.
  - `output_format` 'text' | 'markdown' | 'json' | 'voice'
  - `output_schema` object, nullable: JSON Schema for structured output.
  - `framework` string, nullable: Execution framework.
  - `deep_planning` boolean, nullable: Enable deep planning mode.
  - `enforce_deep_planning` boolean, nullable: Force deep planning for all tasks.
  - `tools` union[], nullable: Tools to attach in the unified simplified shape (same payload as POST /v1/agents/{agent_id}/tools). Additive: these are resolved and merged on top of the agent's existing tools (nothing is removed — use DELETE /v1/agents/{agent_id}/tools/{tool_id} to remove). See CreateAgentRequest.tools for the per-type shape.
    - union
      - AddActionTool: Attach connector operations as agent tools.
        - `type` 'action'
        - `connection_id` string, required: Connector connection id (the connection to call through).
        - `operation_ids` string[], nullable: Operation catalog ids (the `id` field from GET /tools/connectors/{connector_id}/operations). Omit to attach every operation the connection exposes.
      - AddCustomFunctionTool: Attach a custom function as an agent tool.
        - `type` 'custom_function'
        - `custom_function_id` string, required: Custom function id.
        - `hitl_options` object, nullable: Human-approval settings the tool attaches with (same keys as the tool settings `hitl_options`), so it is never callable before its gate.
      - AddMcpTool: Attach an MCP server — either from the org registry (mcp_id) or inline by URL.
        - `type` 'mcp'
        - `mcp_id` string, nullable: MCP server id from the org registry — the `id` from GET /tools?type=mcp. Provide this OR `url`.
        - `url` string, nullable: Remote MCP server URL for an inline (non-registry) MCP. Provide this OR `mcp_id` OR `command`.
        - `mcp_type` 'local' | 'remote'
        - `command` string, nullable: Command that starts a local (stdio) MCP server inside the agent's workspace, e.g. 'npx -y @modelcontextprotocol/server-github'. Provide this OR `url` OR `mcp_id`.
        - `env_vars` object, nullable: Environment for a local MCP server. Use ${NAME} to reference a workspace secret; the value is resolved in the workspace and never stored on the agent.
        - `name` string, nullable: Display name for an inline MCP.
        - `transport` 'stdio' | 'sse' | 'streamable-http'
        - `auth_type` 'api_key' | 'oauth2' | 'custom_headers' | 'sso_user' | 'none'
        - `api_key` string, nullable: API key for an inline MCP when auth_type=api_key.
        - `client_id` string, nullable: OAuth2 client id for an inline MCP (optional; empty enables dynamic registration).
        - `client_secret` string, nullable: OAuth2 client secret for an inline MCP.
        - `additional_scopes` string[], nullable: Extra OAuth2 scopes for an inline MCP.
        - `share_user_token_across_other_agents` boolean, nullable: Share the authorized MCP token across the org's other agents.
        - `share_connection_with_other_users` boolean, nullable: OAuth2 MCP: a caller with no sign-in of their own runs on the agent owner's connection. Off when omitted.
        - `sso_token` string, nullable: auth_type=sso_user: 'access' or 'id' sends the user's SSO token as-is (org admins only), 'exchange' sends it exchanged for sso_audience.
        - `sso_audience` string, nullable: auth_type=sso_user with sso_token=exchange: the audience the user's SSO token is exchanged for.
        - `headers` object, nullable: Custom headers sent to an inline MCP.
        - `allowed_tools` string[], nullable: Optional subset of the MCP server's tools to expose.
        - `health_check_tool` string, nullable: A read-only tool with no required arguments that the connection check calls to prove tool calls work.
        - `health_check_error_text` string, nullable: Text in the health-check answer that means the call failed, for servers that do not flag errors.
        - `register_in_org_registry` boolean, nullable: Remote inline MCP only: also register this server as an org-shared registry entry and attach the agent to it by reference.
      - AddSubAgentTool: Attach another agent as a callable sub-agent tool.
        - `type` 'agent'
        - `agent_id` string, required: Id of the agent to attach as a sub-agent.
      - AddWorkflowTool: Attach a workflow as a callable tool.
        - `type` 'workflow'
        - `workflow_id` string, required: Id of the workflow to attach.
      - AddSkillTool: Attach a skill from the xpander skills catalog as an agent tool.
        - `type` 'skill'
        - `skill_name` string, required: Skill name — the `name` from GET /skills/catalog.
  - `attached_tools` Connector[], nullable: Advanced/low-level: connector connections with operation IDs. Prefer `tools`. See CreateAgentRequest.attached_tools for full documentation.
    - `id` string, required
    - `operation_ids` string[], required
  - `graph` AIAgentGraphItemInput[], nullable: Advanced/low-level: the agent's tool graph. Prefer `tools`. See CreateAgentRequest.graph for full documentation.
    - `id` string, nullable
    - `item_id` string, required
    - `name` string, nullable
    - `type` 'source_node' | 'agent' | 'workflow' | 'tool' | 'human_in_the_loop' | 'xpsleep-agent-delay' | 'custom_agent' | 'storage' | 'local_db' | 'coding_agent' | 'mcp' | 'skills', required
    - `sub_type` 'sdk' | 'task' | 'assistant' | 'webhook' | 'operation' | 'custom_function' | 'local_tool'
    - `targets` string[], required
    - `settings` AIAgentGraphItemSettingsInput
      - `instructions` string, nullable
      - `description` string, nullable
      - `schemas` AIAgentGraphItemSchema
        - `input` object, nullable
        - `output` object, nullable
      - `advanced_filtering_options` AIAgentGraphItemAdvancedFilteringOption
        - `returnables` string[], nullable
        - `searchables` string[], nullable
        - `globally_enabled` boolean, nullable
      - `hitl_options` AIAgentGraphItemHITLSettings
        - `title` string, nullable
        - `description` string, nullable
        - `recipients` string[], nullable
        - `hitl_type` 'slack'
        - `slack_app` string, nullable
        - `should_approve_with_current_user` boolean, nullable
        - `enabled` boolean, nullable
        - `approvers` ToolApprovalApprovers
          - `user_ids` string[], nullable
          - `group_ids` string[], nullable
          - `org_admins` boolean, nullable
        - `on_deny` 'continue' | 'stop'
        - `allowed_scopes` ToolApprovalScope[], nullable
        - `approve_once_per_run` boolean, nullable
        - `timeout_seconds` integer, nullable
        - `channels` string[], nullable
        - `tool_names` string[], nullable
        - `applies_to` 'all' | 'writes', nullable
      - `a2a_options` AIAgentGraphItemA2ASettings
        - `url` string, nullable
      - `coding_agent_settings` AIAgentGraphItemCodingAgentSettings
        - `type` 'codex', nullable
      - `mcp_settings` AIAgentGraphItemMCPSettings
        - `id` string, nullable
        - `type` 'local' | 'remote'
        - `name` string, nullable
        - `command` string, nullable
        - `url` string, nullable
        - `transport` 'stdio' | 'sse' | 'streamable-http'
        - `auth_type` 'api_key' | 'oauth2' | 'custom_headers' | 'sso_user' | 'none'
        - `api_key` string, nullable
        - `use_secrets_manager` boolean, nullable
        - `client_id` string, nullable
        - `client_secret` string, nullable
        - `additional_scopes` string[], nullable
        - `headers` object, nullable
        - `env_vars` object, nullable
        - `allowed_tools` string[], nullable
        - `share_user_token_across_other_agents` boolean, nullable
        - `share_connection_with_other_users` boolean, nullable
        - `sso_token` 'access' | 'id' | 'exchange': How an sso_user server receives the user's token; access and id are sent as-is, so only an org admin may pick them.
        - `sso_audience` string, nullable
        - `health_check_tool` string, nullable
        - `health_check_error_text` string, nullable
        - `connection_status` string, nullable
        - `tools_count` integer, nullable
        - `tools_verified` boolean, nullable
        - `last_checked_at` string, nullable
        - `last_error` string, nullable
      - `connector_settings` AIAgentGraphItemConnectorSettings
        - `background_user_id` string, nullable
        - `auth_mode` 'autonomous' | 'user_authentication': Vault-epic vocabulary; the binding-level clamp ranks these values directly.
        - `share_user_token_across_other_agents` boolean, nullable
        - `approval_policy` ConnectorApprovalPolicy: Connector-wide default, applied to its operations by read-vs-write verb.
          - `read_only` boolean, nullable
          - `mutating` boolean, nullable
        - `write_mode` 'allow' | 'ask' | 'block', nullable
      - `skills_settings` AIAgentGraphItemSkillsSettings
        - `enabled_skills` string[], nullable
      - `use_cache` boolean, nullable
      - `use_mock` boolean, nullable
    - `is_first` boolean, nullable
  - `knowledge_bases` AgentKnowledgeBase[], nullable: Attached knowledge bases.
    - `id` string, required
    - `name` string, nullable
    - `description` string, nullable
    - `strategy` 'vanilla' | 'agentic_rag', required
    - `rw` boolean, nullable
    - `documents` string[], nullable
  - `source_nodes` AIAgentSourceNode[], nullable: Agent trigger entry points.
    - `id` string, nullable
    - `type` 'workbench' | 'sdk' | 'task' | 'assistant' | 'webhook' | 'mcp' | 'a2a' | 'telegram' | 'slack' | 'whatsapp' | 'ms-teams' | 'email' | 'api', required
    - `targets` string[], nullable
    - `metadata` object, nullable
  - `deployment_type` 'serverless' | 'container'
  - `access_scope` 'personal' | 'organizational' | 'project'
  - `environment_id` string, nullable: Target deployment environment.
  - `connectivity_details` union: External agent connection details.
    - AIAgentConnectivityDetailsA2A
      - `custom_headers` object, nullable
      - `auth_type` 'none' | 'api_key' | 'basic' | 'bearer'
      - `api_key_header_name` string, nullable
      - `auth_value` string, nullable
      - `agent_url` string, required
    - AIAgentConnectivityDetailsCurl
      - `custom_headers` object, nullable
      - `auth_type` 'none' | 'api_key' | 'basic' | 'bearer'
      - `api_key_header_name` string, nullable
      - `auth_value` string, nullable
      - `curl_command` string, required
      - `invoke_url` string, nullable
      - `method` string, nullable
      - `prompt_field_name` string, nullable
      - `files_field_name` string, nullable
      - `task_id_field_name` string, nullable
    - object
  - `agno_settings` AgnoSettings
    - `session_storage` boolean, nullable
    - `learning` boolean, nullable
    - `agent_memories` boolean, nullable
    - `agentic_culture` boolean, nullable
    - `user_memories` boolean, nullable
    - `agentic_memory` boolean, nullable
    - `session_summaries` boolean, nullable
    - `num_history_runs` integer, nullable
    - `max_tool_calls_from_history` integer, nullable
    - `tool_call_limit` integer, nullable
    - `coordinate_mode` boolean, nullable
    - `pii_detection_enabled` boolean, nullable
    - `pii_detection_mask` boolean, nullable
    - `prompt_injection_detection_enabled` boolean, nullable
    - `openai_moderation_enabled` boolean, nullable
    - `openai_moderation_categories` string[], nullable
    - `reasoning_tools_enabled` boolean, nullable
    - `max_plan_retries` integer, nullable
  - `harness_settings` HarnessSettingsInput: Runtime settings for an agent whose framework is a CLI harness.
    - `permission_mode` 'full' | 'gated'
    - `max_concurrent_tasks` integer, nullable
    - `workdir_gc_days` integer, nullable
    - `image_tag` string, nullable
    - `approval_hold_hours` integer, nullable
    - `cli_auto_update` boolean, nullable
    - `default_cli` 'claude-code' | 'codex' | 'opencode' | 'xpander': A CLI the harness container can run; chosen per conversation, never per agent.
    - `models` object
    - `available_clis` HarnessCli[]
    - `runtime` 'fleet' | 'legacy': Where an agent's turns run: harness agents on the shared executor fleet; `legacy` is kept for wire compatibility and means not a fleet agent.
    - `resources` HarnessResources: Per-turn ceilings for a harness agent's sandbox on the fleet; every unset field keeps the runner default.
      - `memory_limit` string, nullable
      - `memory_high` string, nullable
      - `cpu` number, nullable
      - `pids` integer, nullable
      - `disk` string, nullable
    - `setup` HarnessSetup: What an imported agent brought along: CLI config files, a one-time setup script, and how project hooks are treated.
      - `files` HarnessSetupFile[]
        - `path` string, required
        - `content` string, required
      - `setup_script` string, nullable
      - `hooks_policy` 'project' | 'off'
    - `shared_work` HarnessSharedWork: How a resident harness agent treats irreversible actions on work other people own: `audit` logs the rule that would fire and lets the call run; `enforce` asks the person through the approval card.
      - `mode` 'audit' | 'enforce'
      - `gated` string[], nullable
      - `blast_radius` HarnessBlastRadius: Past these counts a process asks the person once before its first irreversible step.
        - `prs` integer
        - `files` integer
        - `repos` integer
    - `repos` string[], nullable
    - `browser` boolean, nullable
    - `builtin_tools` HarnessBuiltinTools: The CLI's own built-in tools (`harness`) and the platform's tools (`xpander`); a missing half stays on.
      - `harness` HarnessBuiltinToggle: One built-in tool set switched on or off; None leaves the decision to the next layer down.
        - `enabled` boolean, nullable
      - `xpander` HarnessBuiltinToggle: One built-in tool set switched on or off; None leaves the decision to the next layer down.
        - `enabled` boolean, nullable
  - `task_level_strategies` TaskLevelStrategiesInput: 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.
    - `retry_strategy` OrchestrationRetryStrategy: Strategy for retrying failed orchestration nodes. Attributes: enabled: Whether retry is enabled for this node. max_retries: Maximum number of retry attempts. Defaults to 3.
      - `enabled` boolean, nullable
      - `max_retries` integer, nullable
    - `iterative_strategy` OrchestrationIterativeStrategyInput: Strategy for iteratively executing orchestration nodes. Attributes: enabled: Whether iterative execution is enabled. max_iterations: Maximum number of iterations. Defaults to 3. end_condition: Optional condition to stop iteration early.
      - `enabled` boolean, nullable
      - `max_iterations` integer, nullable
      - `end_condition` OrchestrationCondition: Condition for controlling orchestration flow. Attributes: type: Type of condition (regex, contains, else, or comparison operators). term: The pattern or string to match against. Used for 'regex' and 'contains' types. group_id: Optional group ID for group-based classifier routing. When set, routing matches by group ID instead of term matching. path: Path to extract value from input data (e.g., "input.client_id" or "client_id"). Used for comparison operators (equal, not_equal, gt, lt, gte, lte, not_empty). value: Value to compare against. Used with comparison operators. Not required for 'not_empty' type.
        - `type` 'regex' | 'contains' | 'else' | 'equal' | 'not_equal' | 'gt' | 'lt' | 'gte' | 'lte' | 'not_empty', required: Types of conditions for orchestration control flow. Attributes: Regex: Condition based on regular expression matching. Contains: Condition based on substring containment. Else: Fallback condition that always matches (executed when no other conditions match). Equal: Condition based on equality comparison (path == value). NotEqual: Condition based on inequality comparison (path != value). GreaterThan: Condition based on greater than comparison (path > value). LessThan: Condition based on less than comparison (path < value). GreaterThanOrEqual: Condition based on greater than or equal comparison (path >= value). LessThanOrEqual: Condition based on less than or equal comparison (path <= value). NotEmpty: Condition that checks if a path value is not empty/null.
        - `term` string, nullable
        - `group_id` string, nullable
        - `path` string, nullable
        - `value` unknown
    - `stop_strategy` OrchestrationStopStrategyInput: Strategy for stopping orchestration execution. Attributes: enabled: Whether the stop strategy is enabled. stop_on_failure: Whether to stop the entire orchestration on node failure. stop_on_condition: Optional condition that will stop execution if met.
      - `enabled` boolean, nullable
      - `stop_on_failure` boolean, nullable
      - `stop_on_condition` OrchestrationCondition: Condition for controlling orchestration flow. Attributes: type: Type of condition (regex, contains, else, or comparison operators). term: The pattern or string to match against. Used for 'regex' and 'contains' types. group_id: Optional group ID for group-based classifier routing. When set, routing matches by group ID instead of term matching. path: Path to extract value from input data (e.g., "input.client_id" or "client_id"). Used for comparison operators (equal, not_equal, gt, lt, gte, lte, not_empty). value: Value to compare against. Used with comparison operators. Not required for 'not_empty' type.
        - `type` 'regex' | 'contains' | 'else' | 'equal' | 'not_equal' | 'gt' | 'lt' | 'gte' | 'lte' | 'not_empty', required: Types of conditions for orchestration control flow. Attributes: Regex: Condition based on regular expression matching. Contains: Condition based on substring containment. Else: Fallback condition that always matches (executed when no other conditions match). Equal: Condition based on equality comparison (path == value). NotEqual: Condition based on inequality comparison (path != value). GreaterThan: Condition based on greater than comparison (path > value). LessThan: Condition based on less than comparison (path < value). GreaterThanOrEqual: Condition based on greater than or equal comparison (path >= value). LessThanOrEqual: Condition based on less than or equal comparison (path <= value). NotEmpty: Condition that checks if a path value is not empty/null.
        - `term` string, nullable
        - `group_id` string, nullable
        - `path` string, nullable
        - `value` unknown
    - `max_runs_per_day` integer, nullable
    - `agentic_context_enabled` boolean, nullable
    - `duplication_prevention` DuplicationPreventionSettings: Settings for preventing duplicate event processing in workflows. When enabled, this prevents the same event from triggering a workflow multiple times within a configured time window. Useful for webhooks from services like Stigg or Cal.com that may fire the same event multiple times. Attributes: enabled: Whether duplication prevention is active. ttl_minutes: Time window to consider events as duplicates (default: 10 minutes). selectors: List of dot-notation paths to extract unique ID components from input. Multiple selectors are combined to form a composite key. Examples: - ["messageId"] - single field - ["input.event_id", "input.user_id"] - composite key - ["triggerEvent", "payload.uid"] - Cal.com style
      - `enabled` boolean, nullable
      - `ttl_minutes` integer, nullable
      - `selectors` string[], required
    - `slackbot_formatting_instructions` string, nullable
    - `budget` BudgetSettingsInput: Budget configuration embedded in an agent's task_level_strategies.
      - `agent_budgets` AgentBudgetInput[]
        - `amount_usd` number, required
        - `period` 'daily' | 'weekly' | 'monthly': Recurring window an agent budget resets over.
        - `stop_mode` 'finish_inflight' | 'kill_inflight': How a stop applies to a task that is already running.
        - `thresholds` BudgetThreshold[]
          - `percent` number, required
          - `action` 'warn' | 'stop': What happens when a threshold is crossed. Open set — V2 may add approve/throttle/downgrade.
        - `notify` BudgetNotifyInput: Per-budget notification overrides; unset falls back to the agent's on_budget settings.
          - `channels` object, nullable
          - `max_notifications_per_period` integer, nullable
      - `task_budget` TaskBudgetInput: Overall (non-recurring) spend cap for a single task.
        - `amount_usd` number, required
        - `stop_mode` 'finish_inflight' | 'kill_inflight': How a stop applies to a task that is already running.
        - `thresholds` BudgetThreshold[]
          - `percent` number, required
          - `action` 'warn' | 'stop': What happens when a threshold is crossed. Open set — V2 may add approve/throttle/downgrade.
        - `notify` BudgetNotifyInput: Per-budget notification overrides; unset falls back to the agent's on_budget settings.
          - `channels` object, nullable
          - `max_notifications_per_period` integer, nullable
  - `notification_settings` NotificationSettingsInput: 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.
    - `on_success` object, nullable
    - `on_error` object, nullable
    - `on_budget` object, nullable
  - `voice_id` string, nullable: Voice ID for TTS output.
  - `using_nemo` boolean, nullable: Enable NeMo guardrails.
  - `is_supervised` boolean, nullable: Enable supervised mode.
  - `is_autonomous` boolean, nullable: Run the agent in autonomous mode.
  - `discoverable` boolean, nullable: Omni's entry on the agent's caller list: Omni finds the agent and can send it tasks. Changing it is for the agent owner or an organization admin.
  - `task_callers` AgentTaskCallers
    - `scope` 'org' | 'listed' | 'none'
    - `agent_ids` string[]
    - `updated_by` string, nullable
    - `updated_at` string, nullable
  - `with_auto_context_management` boolean, nullable: Run the SDK automatic context optimizer.
  - `developer_access` boolean, nullable: Allow invocation from the developer API and webhooks.
  - `should_stage_before_publish` boolean, nullable: Stage edits as a draft before publishing. Ignored for agents while drafts are off (the default): every edit saves to live.
  - `gated_commands` object[], nullable: Approval-required workspace commands: a list of {match, unless?, note?, approvers?, channels?}. match is the LITERAL command text (a plain substring, no regex, no escaping); unless names a safe variant that stays exempt (e.g. '--dry-run'). A workspace command containing a match is held for a person's approval before it runs - even on an autonomous/scheduled run. approvers ({user_ids, group_ids}) names who is asked; omit it and the agent's owner is asked. channels (e.g. ['slack']) routes the notification; omit it and each approver's own preferences decide.
  - `personal_plan` AgentPersonalPlan: 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.
    - `user_id` string, required
    - `plan` 'claude' | 'chatgpt', required
    - `account` string, nullable
    - `on_unavailable` 'fallback' | 'wait' | 'stop', nullable
  - `direct_messages` AgentDirectMessages
    - `enabled` boolean
    - `channels` DirectMessageChannel[]
      - `channel` 'slack' | 'whatsapp' | 'telegram' | 'email', required
      - `enabled` boolean
    - `mode` 'first_available' | 'all_selected'
    - `recipients` DirectMessageRecipients
      - `scope` 'listed' | 'org'
      - `user_ids` string[]
      - `group_ids` string[]
  - `slack_settings` AgentSlackSettings
    - `enabled` boolean
    - `send_as` 'user' | 'agent' | 'selected_user'
    - `selected_user_id` string, nullable
    - `dms_enabled` boolean
    - `channel_scope` 'any' | 'listed'
    - `allowed_channels` SlackAllowedChannel[]
      - `id` string, required
      - `name` string
    - `approve_first_contact` boolean
    - `daily_limit` integer
  - `can_self_schedule` boolean, nullable: Allow the agent to schedule its own future runs.
  - `can_archive_conversations` boolean, nullable: Allow the agent to archive and restore its own conversations.
  - `max_self_schedules` integer, nullable: Per-task lifetime cap on chained self-schedules.
  - `on_prem_event_streaming` boolean, nullable: Enable event streaming.
  - `orchestration_nodes` OrchestrationNodeInput[], nullable: Workflow orchestration DAG nodes. Only for type=orchestration workflows.
    - `type` 'custom_function' | 'code' | 'agent' | 'orchestration' | 'classifier' | 'wait' | 'action' | 'guardrail' | 'summarizer' | 'send_to_end' | 'node_pointer' | 'parallel' | 'self_schedule', required: Types of nodes available in an orchestration workflow. Attributes: CustomFunction: Node that executes a custom function. Code: Node that executes arbitrary code. Agent: Node that invokes an AI agent. Orchestration: Node that references another orchestration. Classifier: Node that classifies inputs using LLM. Wait: Node that pauses execution until a condition is met. Action: Node that triggers an action (api). Guardrail: Node that enforces guardrails on inputs using LLM. Summarizer: Node that summarizes or extracts information from inputs using LLM.
    - `id` string
    - `next_node_ids` string[]
    - `name` string, nullable
    - `description` string, nullable
    - `condition` OrchestrationCondition: Condition for controlling orchestration flow. Attributes: type: Type of condition (regex, contains, else, or comparison operators). term: The pattern or string to match against. Used for 'regex' and 'contains' types. group_id: Optional group ID for group-based classifier routing. When set, routing matches by group ID instead of term matching. path: Path to extract value from input data (e.g., "input.client_id" or "client_id"). Used for comparison operators (equal, not_equal, gt, lt, gte, lte, not_empty). value: Value to compare against. Used with comparison operators. Not required for 'not_empty' type.
      - `type` 'regex' | 'contains' | 'else' | 'equal' | 'not_equal' | 'gt' | 'lt' | 'gte' | 'lte' | 'not_empty', required: Types of conditions for orchestration control flow. Attributes: Regex: Condition based on regular expression matching. Contains: Condition based on substring containment. Else: Fallback condition that always matches (executed when no other conditions match). Equal: Condition based on equality comparison (path == value). NotEqual: Condition based on inequality comparison (path != value). GreaterThan: Condition based on greater than comparison (path > value). LessThan: Condition based on less than comparison (path < value). GreaterThanOrEqual: Condition based on greater than or equal comparison (path >= value). LessThanOrEqual: Condition based on less than or equal comparison (path <= value). NotEmpty: Condition that checks if a path value is not empty/null.
      - `term` string, nullable
      - `group_id` string, nullable
      - `path` string, nullable
      - `value` unknown
    - `retry_strategy` OrchestrationRetryStrategy: Strategy for retrying failed orchestration nodes. Attributes: enabled: Whether retry is enabled for this node. max_retries: Maximum number of retry attempts. Defaults to 3.
      - `enabled` boolean, nullable
      - `max_retries` integer, nullable
    - `iterative_strategy` OrchestrationIterativeStrategyInput: Strategy for iteratively executing orchestration nodes. Attributes: enabled: Whether iterative execution is enabled. max_iterations: Maximum number of iterations. Defaults to 3. end_condition: Optional condition to stop iteration early.
      - `enabled` boolean, nullable
      - `max_iterations` integer, nullable
      - `end_condition` OrchestrationCondition: Condition for controlling orchestration flow. Attributes: type: Type of condition (regex, contains, else, or comparison operators). term: The pattern or string to match against. Used for 'regex' and 'contains' types. group_id: Optional group ID for group-based classifier routing. When set, routing matches by group ID instead of term matching. path: Path to extract value from input data (e.g., "input.client_id" or "client_id"). Used for comparison operators (equal, not_equal, gt, lt, gte, lte, not_empty). value: Value to compare against. Used with comparison operators. Not required for 'not_empty' type.
        - `type` 'regex' | 'contains' | 'else' | 'equal' | 'not_equal' | 'gt' | 'lt' | 'gte' | 'lte' | 'not_empty', required: Types of conditions for orchestration control flow. Attributes: Regex: Condition based on regular expression matching. Contains: Condition based on substring containment. Else: Fallback condition that always matches (executed when no other conditions match). Equal: Condition based on equality comparison (path == value). NotEqual: Condition based on inequality comparison (path != value). GreaterThan: Condition based on greater than comparison (path > value). LessThan: Condition based on less than comparison (path < value). GreaterThanOrEqual: Condition based on greater than or equal comparison (path >= value). LessThanOrEqual: Condition based on less than or equal comparison (path <= value). NotEmpty: Condition that checks if a path value is not empty/null.
        - `term` string, nullable
        - `group_id` string, nullable
        - `path` string, nullable
        - `value` unknown
    - `stop_strategy` OrchestrationStopStrategyInput: Strategy for stopping orchestration execution. Attributes: enabled: Whether the stop strategy is enabled. stop_on_failure: Whether to stop the entire orchestration on node failure. stop_on_condition: Optional condition that will stop execution if met.
      - `enabled` boolean, nullable
      - `stop_on_failure` boolean, nullable
      - `stop_on_condition` OrchestrationCondition: Condition for controlling orchestration flow. Attributes: type: Type of condition (regex, contains, else, or comparison operators). term: The pattern or string to match against. Used for 'regex' and 'contains' types. group_id: Optional group ID for group-based classifier routing. When set, routing matches by group ID instead of term matching. path: Path to extract value from input data (e.g., "input.client_id" or "client_id"). Used for comparison operators (equal, not_equal, gt, lt, gte, lte, not_empty). value: Value to compare against. Used with comparison operators. Not required for 'not_empty' type.
        - `type` 'regex' | 'contains' | 'else' | 'equal' | 'not_equal' | 'gt' | 'lt' | 'gte' | 'lte' | 'not_empty', required: Types of conditions for orchestration control flow. Attributes: Regex: Condition based on regular expression matching. Contains: Condition based on substring containment. Else: Fallback condition that always matches (executed when no other conditions match). Equal: Condition based on equality comparison (path == value). NotEqual: Condition based on inequality comparison (path != value). GreaterThan: Condition based on greater than comparison (path > value). LessThan: Condition based on less than comparison (path < value). GreaterThanOrEqual: Condition based on greater than or equal comparison (path >= value). LessThanOrEqual: Condition based on less than or equal comparison (path <= value). NotEmpty: Condition that checks if a path value is not empty/null.
        - `term` string, nullable
        - `group_id` string, nullable
        - `path` string, nullable
        - `value` unknown
    - `definition` union, required
      - OrchestrationCodeNode: Node that executes arbitrary code. Attributes: code: The code string to execute.
        - `code` string, required
      - OrchestrationClassifierNodeInput: Node that uses LLM to classify inputs into groups. Attributes: groups: List of classification groups to evaluate against. output_type: Expected output format. Defaults to Text. output_schema: JSON schema for structured output validation. instructions: Classification or transformation instructions for the LLM. examples: Example inputs/outputs to guide the LLM behavior. settings: LLM configuration settings.
        - `groups` ClassificationGroup[], required
          - `id` string
          - `name` string, required
          - `evaluation_criteria` string, required
          - `auto_extract_relevant_data` boolean, nullable
          - `data_extraction_keys` string[], nullable
        - `output_type` 'text' | 'markdown' | 'json' | 'voice'
        - `output_schema` object, nullable
        - `instructions` string, nullable
        - `examples` string[], nullable
        - `settings` OrchestrationClassifierNodeLLMSettings, required: LLM configuration for classifier nodes. Attributes: model_provider: The LLM provider to use. Defaults to AmazonBedrock. model_name: Specific model identifier. Defaults to "global.anthropic.claude-opus-5-5". llm_credentials_key: Key identifier for stored credentials. llm_credentials_key_type: Type of credential key storage. Defaults to XPander. llm_credentials: Direct credential object if not using stored credentials. llm_api_base: Alternative API Base for the LLM. llm_extra_headers: Extra headers to be set to LLM Requests.
          - `model_provider` 'openai' | 'nim' | 'amazon_bedrock' | 'azure_ai_foundary' | 'huggingFace' | 'friendlyAI' | 'anthropic' | 'gemini' | 'fireworks' | 'google_ai_studio' | 'helicone' | 'bytedance' | 'tzafon_lightcone' | 'cerebras' | 'open_router' | 'nebius' | 'cloudflare_ai_gw' | 'z_ai'
          - `model_name` string, nullable
          - `llm_credentials_key` string, nullable
          - `llm_credentials_key_type` 'xpander' | 'custom'
          - `llm_credentials` LLMCredentials
            - `name` string, required
            - `description` string, nullable
            - `value` string, required
          - `llm_api_base` string, nullable
          - `llm_extra_headers` object, nullable
      - OrchestrationPointerNode: Node that references an external asset (agent, function, or orchestration). Attributes: asset_id: Unique identifier of the asset to execute. type: Type of asset being referenced. output_type: Expected output format. Defaults to Text. output_schema: JSON schema for structured output validation. instructions: Optional instructions for the pointer node (Action only). instructions_mode: Mode to use for pointer node, specifically for agent nodes. ignore_response: Should ignore the node result and proceed with previous result?. persist_thread_id: Should persist the thread in agent nodes? default (True). schema_override: Optional schema override with permanentValue fields for fixed values.
        - `asset_id` string, required
        - `type` 'agent' | 'custom_function' | 'orchestration' | 'action', required
        - `output_type` 'text' | 'markdown' | 'json' | 'voice'
        - `output_schema` object, nullable
        - `instructions` string, nullable
        - `instructions_mode` 'replace' | 'append': Modes for instruction usage in pointer node. Attributes: Replace: Replaces the traget asset instructions. Append: Appends to the traget asset instructions.
        - `ignore_response` boolean, nullable
        - `persist_thread_id` boolean, nullable
        - `schema_override` SchemaOverride: Schema override for workflow action nodes. Allows setting permanent (fixed) values for tool input properties. Fields with permanentValue will be removed from the schema sent to the LLM and the permanent values will be applied to the payload before execution. Attributes: input: Input schema with permanentValue fields to override LLM-generated values.
          - `input` object, nullable
      - OrchestrationWaitNodeInput: Node that pauses execution until an external event occurs. Attributes: type: Type of wait event (webhook or human-in-the-loop). definition: Notification configuration for triggering continuation.
        - `type` 'webhook' | 'hitl', required
        - `definition` union, required
          - EmailNotificationSettings: Configuration for email notifications. Attributes: to: List of recipient email addresses.
            - `subject` string, nullable
            - `body` string, nullable
            - `approve_button_text` string, nullable
            - `deny_button_text` string, nullable
            - `logo_url` string, nullable
            - `to` string[], required
          - SlackNotificationSettings: Configuration for Slack notifications. Attributes: channels: List of Slack channel IDs or names to post to. connection_id: connector_organization id of a connected Slack workspace. When set and `credentials.access_token` is absent, the delivery path resolves the token server-side from the connection (the client never persists the token). credentials: Slack API authentication credentials. Optional — defaults to empty so a connection_id-only target parses; the token is resolved at send time.
            - `subject` string, nullable
            - `body` string, nullable
            - `approve_button_text` string, nullable
            - `deny_button_text` string, nullable
            - `logo_url` string, nullable
            - `channels` string[], required
            - `connection_id` string, nullable
            - `credentials` SlackCredentials: Slack API authentication credentials. Attributes: authed_user_id: Authenticated user's Slack ID. access_token: OAuth access token for API calls. client_id: Slack app client ID. client_secret: Slack app client secret. verification_token: Token for verifying requests from Slack. signing_secret: Secret for validating webhook signatures. app_configuration_token: Token for app configuration. app_configuration_refresh_token: Refresh token for app configuration.
              - …
          - WebhookNotificationSettings: Configuration for webhook notifications. Attributes: url: Target webhook URL to POST notification data. headers: Optional HTTP headers to include in the webhook request.
            - `subject` string, nullable
            - `body` string, nullable
            - `approve_button_text` string, nullable
            - `deny_button_text` string, nullable
            - `logo_url` string, nullable
            - `url` string, required
            - `headers` object, nullable
      - OrchestrationGuardrailNodeInput: Node that uses LLM to evaluate input against pass/fail criteria. This node works like a classifier with exactly 2 groups: "pass" and "fail". The user defines evaluation_criteria for each group. Routing behavior: - If guardrail passes: routes to downstream node with condition group_id="pass" - If guardrail fails: routes to downstream node with condition group_id="fail" - If no fail route exists: falls back to end nodes (end-summarizer or end-classifier) - A pass route is REQUIRED; fail route is optional. Attributes: groups: List of 2 ClassificationGroup objects with IDs "pass" and "fail". Each group has evaluation_criteria defined by the user. examples: Example inputs/outputs to guide the LLM behavior. settings: LLM configuration settings.
        - `groups` ClassificationGroup[], required
          - `id` string
          - `name` string, required
          - `evaluation_criteria` string, required
          - `auto_extract_relevant_data` boolean, nullable
          - `data_extraction_keys` string[], nullable
        - `examples` string[], nullable
        - `settings` OrchestrationClassifierNodeLLMSettings, required: LLM configuration for classifier nodes. Attributes: model_provider: The LLM provider to use. Defaults to AmazonBedrock. model_name: Specific model identifier. Defaults to "global.anthropic.claude-opus-5-5". llm_credentials_key: Key identifier for stored credentials. llm_credentials_key_type: Type of credential key storage. Defaults to XPander. llm_credentials: Direct credential object if not using stored credentials. llm_api_base: Alternative API Base for the LLM. llm_extra_headers: Extra headers to be set to LLM Requests.
          - `model_provider` 'openai' | 'nim' | 'amazon_bedrock' | 'azure_ai_foundary' | 'huggingFace' | 'friendlyAI' | 'anthropic' | 'gemini' | 'fireworks' | 'google_ai_studio' | 'helicone' | 'bytedance' | 'tzafon_lightcone' | 'cerebras' | 'open_router' | 'nebius' | 'cloudflare_ai_gw' | 'z_ai'
          - `model_name` string, nullable
          - `llm_credentials_key` string, nullable
          - `llm_credentials_key_type` 'xpander' | 'custom'
          - `llm_credentials` LLMCredentials
            - `name` string, required
            - `description` string, nullable
            - `value` string, required
          - `llm_api_base` string, nullable
          - `llm_extra_headers` object, nullable
      - OrchestrationSummarizerNodeInput: Node that processes large payloads and answers specific questions. This node uses an LLM to summarize or extract information from large inputs. Attributes: instructions: Summarization or question-answering instructions for the LLM. examples: Example inputs/outputs to guide the LLM behavior. settings: LLM configuration settings.
        - `instructions` string, required
        - `examples` string[], nullable
        - `settings` OrchestrationClassifierNodeLLMSettings, required: LLM configuration for classifier nodes. Attributes: model_provider: The LLM provider to use. Defaults to AmazonBedrock. model_name: Specific model identifier. Defaults to "global.anthropic.claude-opus-5-5". llm_credentials_key: Key identifier for stored credentials. llm_credentials_key_type: Type of credential key storage. Defaults to XPander. llm_credentials: Direct credential object if not using stored credentials. llm_api_base: Alternative API Base for the LLM. llm_extra_headers: Extra headers to be set to LLM Requests.
          - `model_provider` 'openai' | 'nim' | 'amazon_bedrock' | 'azure_ai_foundary' | 'huggingFace' | 'friendlyAI' | 'anthropic' | 'gemini' | 'fireworks' | 'google_ai_studio' | 'helicone' | 'bytedance' | 'tzafon_lightcone' | 'cerebras' | 'open_router' | 'nebius' | 'cloudflare_ai_gw' | 'z_ai'
          - `model_name` string, nullable
          - `llm_credentials_key` string, nullable
          - `llm_credentials_key_type` 'xpander' | 'custom'
          - `llm_credentials` LLMCredentials
            - `name` string, required
            - `description` string, nullable
            - `value` string, required
          - `llm_api_base` string, nullable
          - `llm_extra_headers` object, nullable
      - OrchestrationSendToEndNode: Node that routes execution to end nodes or finishes the workflow. When triggered, this node will: 1. Route to end nodes (end-summarizer, end-classifier) if they exist 2. Finish workflow execution immediately if no end nodes exist Attributes: message: Optional message or reason for finishing the workflow.
        - `message` string, nullable
      - OrchestrationSelfScheduleNode: Node that pauses the workflow and schedules itself to resume at a later time. At runtime the worker's self-schedule executor: 1. LLM-parses ``when`` (free-text like "in 1 hour", "next Monday 9am") into an absolute ISO-8601 ``run_at`` using the current datetime / user timezone. 2. Creates a row in ``ai_agents_self_schedules`` with the current ``task_id`` and ``workflow_next_node = target_node_id``. 3. Pauses the task. When APScheduler fires the row, the same task is re-invoked with ``payload_extension={"workflow_next_node": target_node_id}`` and the worker resumes execution starting from the target node, re-running target + its forward cone and skipping everything outside that cone. ``target_node_id`` may point to ANY node in the orchestration (forward, backward, or sibling). Backward jumps are bounded by ``max_reschedules`` so loops cannot run away. Attributes: when: Free-text schedule expression, parsed by the worker via an LLM. target_node_id: The id of the node to resume at. Must exist in the orchestration; no topological constraint. prompt: Optional instruction appended to the upstream node's result before being sent as the scheduled run's prompt. If both the upstream result and this prompt are empty, the node fails rather than creating an empty row. max_reschedules: Maximum number of times this node may fire during a single task lifecycle. Once reached, the executor falls through and the graph proceeds via ``next_node_ids``. Defaults to 1.
        - `when` string, required
        - `target_node_id` string, required
        - `prompt` string, nullable
        - `max_reschedules` integer
      - OrchestrationNodePointerDefinition: Definition for a NodePointer node that acts as a graph-position jump. A NodePointer jumps execution to another node's position in the graph. At resolution time, the pointer adopts the source node's definition, type, AND next_node_ids — so after executing the source's logic, the flow continues to the source's original downstream targets. The pointer keeps its own id, name, condition, and strategies. Attributes: source_node_id: ID of the node to jump to.
        - `source_node_id` string, required
      - OrchestrationParallelNodeInput: Node that executes multiple child nodes in parallel. All child nodes receive the same input (the output of the preceding node). When all child nodes complete, their results are combined: - JSON outputs are merged into a single JSON object keyed by node name. - String outputs are concatenated with node name headers. Attributes: nodes: List of child OrchestrationNode objects to execute in parallel. output_type: Expected output format for the combined result. Defaults to Text. output_schema: JSON schema for structured output validation of the combined result. output_instructions: Instructions for transforming the combined output into the schema.
        - `nodes` OrchestrationNodeInput[], required
        - `output_type` 'text' | 'markdown' | 'json' | 'voice'
        - `output_schema` object, nullable
        - `output_instructions` string, nullable
    - `input_type` 'text' | 'markdown' | 'json' | 'voice'
    - `input_schema` object, nullable
    - `input_instructions` string, nullable
    - `agentic_context_input_instructions` string, nullable
    - `agentic_context_output_instructions` string, nullable
    - `return_this` boolean, nullable
  - `use_oidc_pre_auth` boolean, nullable: Enable OIDC pre-authentication.
  - `pre_auth_audiences` string[], nullable: Allowed OIDC audiences.
  - `use_oidc_pre_auth_token_for_llm` boolean, nullable: Forward OIDC token to LLM.
  - `oidc_pre_auth_token_llm_audience` string, nullable: OIDC audience for LLM access.
  - `oidc_pre_auth_token_mcp_audience` string, nullable: OIDC audience for MCP access.

## Response `200`

Successful Response

- AIAgent
  - `id` string, nullable
  - `unique_name` string, nullable
  - `origin_template` string, nullable
  - `environment_id` string, nullable
  - `runtime_environment_id` string, nullable
  - `deployment_type` 'serverless' | 'container'
  - `prompts` string[], nullable
  - `is_latest` boolean, nullable
  - `has_pending_changes` boolean, nullable
  - `deep_planning` boolean, nullable
  - `enforce_deep_planning` boolean, nullable
  - `use_agent_gateway` boolean, nullable
  - `name` string, required
  - `connectivity_details` union
    - AIAgentConnectivityDetailsA2A
      - `custom_headers` object, nullable
      - `auth_type` 'none' | 'api_key' | 'basic' | 'bearer'
      - `api_key_header_name` string, nullable
      - `auth_value` string, nullable
      - `agent_url` string, required
    - AIAgentConnectivityDetailsCurl
      - `custom_headers` object, nullable
      - `auth_type` 'none' | 'api_key' | 'basic' | 'bearer'
      - `api_key_header_name` string, nullable
      - `auth_value` string, nullable
      - `curl_command` string, required
      - `invoke_url` string, nullable
      - `method` string, nullable
      - `prompt_field_name` string, nullable
      - `files_field_name` string, nullable
      - `task_id_field_name` string, nullable
    - object
  - `framework` string, nullable
  - `description` string, nullable
  - `tools` unknown[], nullable
    - unknown
  - `icon` string, nullable
  - `avatar` string, nullable
  - `source_nodes` AIAgentSourceNode[], nullable
    - `id` string, nullable
    - `type` 'workbench' | 'sdk' | 'task' | 'assistant' | 'webhook' | 'mcp' | 'a2a' | 'telegram' | 'slack' | 'whatsapp' | 'ms-teams' | 'email' | 'api', required
    - `targets` string[], nullable
    - `metadata` object, nullable
  - `attached_tools` Connector[], nullable
    - `id` string, required
    - `operation_ids` string[], required
  - `access_scope` 'personal' | 'organizational' | 'project'
  - `project_id` string, nullable
  - `instructions` AIAgentInstructions
    - `role` string[], nullable
    - `goal` string[], nullable
    - `general` string, nullable
    - `dynamic_prompt_enabled` boolean, nullable
    - `dynamic_prompt_code` string, nullable
    - `dynamic_prompt_position` 'before' | 'after', nullable
  - `oas` object, nullable
  - `graph` AIAgentGraphItemOutput[], nullable
    - `id` string, nullable
    - `item_id` string, required
    - `name` string, nullable
    - `type` 'source_node' | 'agent' | 'workflow' | 'tool' | 'human_in_the_loop' | 'xpsleep-agent-delay' | 'custom_agent' | 'storage' | 'local_db' | 'coding_agent' | 'mcp' | 'skills', required
    - `sub_type` 'sdk' | 'task' | 'assistant' | 'webhook' | 'operation' | 'custom_function' | 'local_tool'
    - `targets` string[], required
    - `settings` AIAgentGraphItemSettingsOutput
      - `instructions` string, nullable
      - `description` string, nullable
      - `schemas` AIAgentGraphItemSchema
        - `input` object, nullable
        - `output` object, nullable
      - `advanced_filtering_options` AIAgentGraphItemAdvancedFilteringOption
        - `returnables` string[], nullable
        - `searchables` string[], nullable
        - `globally_enabled` boolean, nullable
      - `hitl_options` AIAgentGraphItemHITLSettings
        - `title` string, nullable
        - `description` string, nullable
        - `recipients` string[], nullable
        - `hitl_type` 'slack'
        - `slack_app` string, nullable
        - `should_approve_with_current_user` boolean, nullable
        - `enabled` boolean, nullable
        - `approvers` ToolApprovalApprovers
          - `user_ids` string[], nullable
          - `group_ids` string[], nullable
          - `org_admins` boolean, nullable
        - `on_deny` 'continue' | 'stop'
        - `allowed_scopes` ToolApprovalScope[], nullable
        - `approve_once_per_run` boolean, nullable
        - `timeout_seconds` integer, nullable
        - `channels` string[], nullable
        - `tool_names` string[], nullable
        - `applies_to` 'all' | 'writes', nullable
      - `a2a_options` AIAgentGraphItemA2ASettings
        - `url` string, nullable
      - `coding_agent_settings` AIAgentGraphItemCodingAgentSettings
        - `type` 'codex', nullable
      - `mcp_settings` AIAgentGraphItemMCPSettings
        - `id` string, nullable
        - `type` 'local' | 'remote'
        - `name` string, nullable
        - `command` string, nullable
        - `url` string, nullable
        - `transport` 'stdio' | 'sse' | 'streamable-http'
        - `auth_type` 'api_key' | 'oauth2' | 'custom_headers' | 'sso_user' | 'none'
        - `api_key` string, nullable
        - `use_secrets_manager` boolean, nullable
        - `client_id` string, nullable
        - `client_secret` string, nullable
        - `additional_scopes` string[], nullable
        - `headers` object, nullable
        - `env_vars` object, nullable
        - `allowed_tools` string[], nullable
        - `share_user_token_across_other_agents` boolean, nullable
        - `share_connection_with_other_users` boolean, nullable
        - `sso_token` 'access' | 'id' | 'exchange': How an sso_user server receives the user's token; access and id are sent as-is, so only an org admin may pick them.
        - `sso_audience` string, nullable
        - `health_check_tool` string, nullable
        - `health_check_error_text` string, nullable
        - `connection_status` string, nullable
        - `tools_count` integer, nullable
        - `tools_verified` boolean, nullable
        - `last_checked_at` string, nullable
        - `last_error` string, nullable
      - `connector_settings` AIAgentGraphItemConnectorSettings
        - `background_user_id` string, nullable
        - `auth_mode` 'autonomous' | 'user_authentication': Vault-epic vocabulary; the binding-level clamp ranks these values directly.
        - `share_user_token_across_other_agents` boolean, nullable
        - `approval_policy` ConnectorApprovalPolicy: Connector-wide default, applied to its operations by read-vs-write verb.
          - `read_only` boolean, nullable
          - `mutating` boolean, nullable
        - `write_mode` 'allow' | 'ask' | 'block', nullable
      - `skills_settings` AIAgentGraphItemSkillsSettings
        - `enabled_skills` string[], nullable
      - `use_cache` boolean, nullable
      - `use_mock` boolean, nullable
    - `is_first` boolean, nullable
  - `is_omni` boolean, nullable
  - `kind` 'gateway' | 'cloud_code': A platform-made agent: the gateway one is hidden from lists, counts and delegation; every kind stays out of the agents quota.
  - `skills` object[], nullable
  - `runtime_environment` object, nullable
  - `company_brain_enabled` boolean
  - `agent_brains` string[], nullable
  - `secret_bindings` object[], nullable
  - `required_secrets` object[]
  - `gated_commands` object[], nullable
  - `status` 'DRAFT' | 'ACTIVE' | 'INACTIVE': Enumeration of possible agent statuses. Attributes: DRAFT: Agent is in a draft state. ACTIVE: Agent is active and operational. INACTIVE: Agent is inactive and not operational.
  - `knowledge_bases` AgentKnowledgeBase[], nullable
    - `id` string, required
    - `name` string, nullable
    - `description` string, nullable
    - `strategy` 'vanilla' | 'agentic_rag', required
    - `rw` boolean, nullable
    - `documents` string[], nullable
  - `version` integer, nullable
  - `organization_id` string, required
  - `created_by` string, nullable
  - `default_user_id` string, nullable: Organization user to run as when a non-UI invocation has no resolved user.
  - `background_user_overrides` object
  - `created_at` string, date-time, nullable
  - `type` 'manager' | 'regular' | 'a2a' | 'curl' | 'orchestration': Enumeration of the agent types. Attributes: Manager: marks the agent as a Managing agent. Regular: marks the agent as a regular agent. A2A: marks the agent as an external agent used via A2A protocol. Curl: marks the agent as an external agent used via a CURL. Orchestration: marks the agent as an Orchestration object.
  - `using_nemo` boolean, nullable
  - `deletable` boolean, nullable
  - `model_provider` 'openai' | 'nim' | 'amazon_bedrock' | 'azure_ai_foundary' | 'huggingFace' | 'friendlyAI' | 'anthropic' | 'gemini' | 'fireworks' | 'google_ai_studio' | 'helicone' | 'bytedance' | 'tzafon_lightcone' | 'cerebras' | 'open_router' | 'nebius' | 'cloudflare_ai_gw' | 'z_ai'
  - `model_name` string, nullable
  - `llm_reasoning_effort` 'low' | 'medium' | 'high' | 'xhigh'
  - `llm_api_base` string, nullable
  - `output_format` 'text' | 'markdown' | 'json' | 'voice'
  - `voice_id` string, nullable
  - `output_schema` object, nullable
  - `llm_credentials_key` string, nullable
  - `llm_credentials_key_type` 'xpander' | 'custom'
  - `llm_credentials` LLMCredentials
    - `name` string, required
    - `description` string, nullable
    - `value` string, required
  - `llm_extra_headers` object, nullable
  - `expected_output` string, nullable
  - `agno_settings` AgnoSettings
    - `session_storage` boolean, nullable
    - `learning` boolean, nullable
    - `agent_memories` boolean, nullable
    - `agentic_culture` boolean, nullable
    - `user_memories` boolean, nullable
    - `agentic_memory` boolean, nullable
    - `session_summaries` boolean, nullable
    - `num_history_runs` integer, nullable
    - `max_tool_calls_from_history` integer, nullable
    - `tool_call_limit` integer, nullable
    - `coordinate_mode` boolean, nullable
    - `pii_detection_enabled` boolean, nullable
    - `pii_detection_mask` boolean, nullable
    - `prompt_injection_detection_enabled` boolean, nullable
    - `openai_moderation_enabled` boolean, nullable
    - `openai_moderation_categories` string[], nullable
    - `reasoning_tools_enabled` boolean, nullable
    - `max_plan_retries` integer, nullable
  - `harness_settings` HarnessSettingsOutput: Runtime settings for an agent whose framework is a CLI harness.
    - `permission_mode` 'full' | 'gated'
    - `max_concurrent_tasks` integer, nullable
    - `workdir_gc_days` integer, nullable
    - `image_tag` string, nullable
    - `approval_hold_hours` integer, nullable
    - `cli_auto_update` boolean, nullable
    - `default_cli` 'claude-code' | 'codex' | 'opencode' | 'xpander': A CLI the harness container can run; chosen per conversation, never per agent.
    - `models` object
    - `available_clis` HarnessCli[]
    - `runtime` 'fleet' | 'legacy': Where an agent's turns run: harness agents on the shared executor fleet; `legacy` is kept for wire compatibility and means not a fleet agent.
    - `resources` HarnessResources: Per-turn ceilings for a harness agent's sandbox on the fleet; every unset field keeps the runner default.
      - `memory_limit` string, nullable
      - `memory_high` string, nullable
      - `cpu` number, nullable
      - `pids` integer, nullable
      - `disk` string, nullable
    - `setup` HarnessSetup: What an imported agent brought along: CLI config files, a one-time setup script, and how project hooks are treated.
      - `files` HarnessSetupFile[]
        - `path` string, required
        - `content` string, required
      - `setup_script` string, nullable
      - `hooks_policy` 'project' | 'off'
    - `shared_work` HarnessSharedWork: How a resident harness agent treats irreversible actions on work other people own: `audit` logs the rule that would fire and lets the call run; `enforce` asks the person through the approval card.
      - `mode` 'audit' | 'enforce'
      - `gated` string[], nullable
      - `blast_radius` HarnessBlastRadius: Past these counts a process asks the person once before its first irreversible step.
        - `prs` integer
        - `files` integer
        - `repos` integer
    - `repos` string[], nullable
    - `browser` boolean, nullable
    - `builtin_tools` HarnessBuiltinTools: The CLI's own built-in tools (`harness`) and the platform's tools (`xpander`); a missing half stays on.
      - `harness` HarnessBuiltinToggle: One built-in tool set switched on or off; None leaves the decision to the next layer down.
        - `enabled` boolean, nullable
      - `xpander` HarnessBuiltinToggle: One built-in tool set switched on or off; None leaves the decision to the next layer down.
        - `enabled` boolean, nullable
  - `on_prem_event_streaming` boolean, nullable
  - `is_supervised` boolean, nullable
  - `orchestration_nodes` OrchestrationNodeOutput[], nullable
    - `type` 'custom_function' | 'code' | 'agent' | 'orchestration' | 'classifier' | 'wait' | 'action' | 'guardrail' | 'summarizer' | 'send_to_end' | 'node_pointer' | 'parallel' | 'self_schedule', required: Types of nodes available in an orchestration workflow. Attributes: CustomFunction: Node that executes a custom function. Code: Node that executes arbitrary code. Agent: Node that invokes an AI agent. Orchestration: Node that references another orchestration. Classifier: Node that classifies inputs using LLM. Wait: Node that pauses execution until a condition is met. Action: Node that triggers an action (api). Guardrail: Node that enforces guardrails on inputs using LLM. Summarizer: Node that summarizes or extracts information from inputs using LLM.
    - `id` string
    - `next_node_ids` string[]
    - `name` string, nullable
    - `description` string, nullable
    - `condition` OrchestrationCondition: Condition for controlling orchestration flow. Attributes: type: Type of condition (regex, contains, else, or comparison operators). term: The pattern or string to match against. Used for 'regex' and 'contains' types. group_id: Optional group ID for group-based classifier routing. When set, routing matches by group ID instead of term matching. path: Path to extract value from input data (e.g., "input.client_id" or "client_id"). Used for comparison operators (equal, not_equal, gt, lt, gte, lte, not_empty). value: Value to compare against. Used with comparison operators. Not required for 'not_empty' type.
      - `type` 'regex' | 'contains' | 'else' | 'equal' | 'not_equal' | 'gt' | 'lt' | 'gte' | 'lte' | 'not_empty', required: Types of conditions for orchestration control flow. Attributes: Regex: Condition based on regular expression matching. Contains: Condition based on substring containment. Else: Fallback condition that always matches (executed when no other conditions match). Equal: Condition based on equality comparison (path == value). NotEqual: Condition based on inequality comparison (path != value). GreaterThan: Condition based on greater than comparison (path > value). LessThan: Condition based on less than comparison (path < value). GreaterThanOrEqual: Condition based on greater than or equal comparison (path >= value). LessThanOrEqual: Condition based on less than or equal comparison (path <= value). NotEmpty: Condition that checks if a path value is not empty/null.
      - `term` string, nullable
      - `group_id` string, nullable
      - `path` string, nullable
      - `value` unknown
    - `retry_strategy` OrchestrationRetryStrategy: Strategy for retrying failed orchestration nodes. Attributes: enabled: Whether retry is enabled for this node. max_retries: Maximum number of retry attempts. Defaults to 3.
      - `enabled` boolean, nullable
      - `max_retries` integer, nullable
    - `iterative_strategy` OrchestrationIterativeStrategyOutput: Strategy for iteratively executing orchestration nodes. Attributes: enabled: Whether iterative execution is enabled. max_iterations: Maximum number of iterations. Defaults to 3. end_condition: Optional condition to stop iteration early.
      - `enabled` boolean, nullable
      - `max_iterations` integer, nullable
      - `end_condition` OrchestrationCondition: Condition for controlling orchestration flow. Attributes: type: Type of condition (regex, contains, else, or comparison operators). term: The pattern or string to match against. Used for 'regex' and 'contains' types. group_id: Optional group ID for group-based classifier routing. When set, routing matches by group ID instead of term matching. path: Path to extract value from input data (e.g., "input.client_id" or "client_id"). Used for comparison operators (equal, not_equal, gt, lt, gte, lte, not_empty). value: Value to compare against. Used with comparison operators. Not required for 'not_empty' type.
        - `type` 'regex' | 'contains' | 'else' | 'equal' | 'not_equal' | 'gt' | 'lt' | 'gte' | 'lte' | 'not_empty', required: Types of conditions for orchestration control flow. Attributes: Regex: Condition based on regular expression matching. Contains: Condition based on substring containment. Else: Fallback condition that always matches (executed when no other conditions match). Equal: Condition based on equality comparison (path == value). NotEqual: Condition based on inequality comparison (path != value). GreaterThan: Condition based on greater than comparison (path > value). LessThan: Condition based on less than comparison (path < value). GreaterThanOrEqual: Condition based on greater than or equal comparison (path >= value). LessThanOrEqual: Condition based on less than or equal comparison (path <= value). NotEmpty: Condition that checks if a path value is not empty/null.
        - `term` string, nullable
        - `group_id` string, nullable
        - `path` string, nullable
        - `value` unknown
    - `stop_strategy` OrchestrationStopStrategyOutput: Strategy for stopping orchestration execution. Attributes: enabled: Whether the stop strategy is enabled. stop_on_failure: Whether to stop the entire orchestration on node failure. stop_on_condition: Optional condition that will stop execution if met.
      - `enabled` boolean, nullable
      - `stop_on_failure` boolean, nullable
      - `stop_on_condition` OrchestrationCondition: Condition for controlling orchestration flow. Attributes: type: Type of condition (regex, contains, else, or comparison operators). term: The pattern or string to match against. Used for 'regex' and 'contains' types. group_id: Optional group ID for group-based classifier routing. When set, routing matches by group ID instead of term matching. path: Path to extract value from input data (e.g., "input.client_id" or "client_id"). Used for comparison operators (equal, not_equal, gt, lt, gte, lte, not_empty). value: Value to compare against. Used with comparison operators. Not required for 'not_empty' type.
        - `type` 'regex' | 'contains' | 'else' | 'equal' | 'not_equal' | 'gt' | 'lt' | 'gte' | 'lte' | 'not_empty', required: Types of conditions for orchestration control flow. Attributes: Regex: Condition based on regular expression matching. Contains: Condition based on substring containment. Else: Fallback condition that always matches (executed when no other conditions match). Equal: Condition based on equality comparison (path == value). NotEqual: Condition based on inequality comparison (path != value). GreaterThan: Condition based on greater than comparison (path > value). LessThan: Condition based on less than comparison (path < value). GreaterThanOrEqual: Condition based on greater than or equal comparison (path >= value). LessThanOrEqual: Condition based on less than or equal comparison (path <= value). NotEmpty: Condition that checks if a path value is not empty/null.
        - `term` string, nullable
        - `group_id` string, nullable
        - `path` string, nullable
        - `value` unknown
    - `definition` union, required
      - OrchestrationCodeNode: Node that executes arbitrary code. Attributes: code: The code string to execute.
        - `code` string, required
      - OrchestrationClassifierNodeOutput: Node that uses LLM to classify inputs into groups. Attributes: groups: List of classification groups to evaluate against. output_type: Expected output format. Defaults to Text. output_schema: JSON schema for structured output validation. instructions: Classification or transformation instructions for the LLM. examples: Example inputs/outputs to guide the LLM behavior. settings: LLM configuration settings.
        - `groups` ClassificationGroup[], required
          - `id` string
          - `name` string, required
          - `evaluation_criteria` string, required
          - `auto_extract_relevant_data` boolean, nullable
          - `data_extraction_keys` string[], nullable
        - `output_type` 'text' | 'markdown' | 'json' | 'voice'
        - `output_schema` object, nullable
        - `instructions` string, nullable
        - `examples` string[], nullable
        - `settings` OrchestrationClassifierNodeLLMSettings, required: LLM configuration for classifier nodes. Attributes: model_provider: The LLM provider to use. Defaults to AmazonBedrock. model_name: Specific model identifier. Defaults to "global.anthropic.claude-opus-5-5". llm_credentials_key: Key identifier for stored credentials. llm_credentials_key_type: Type of credential key storage. Defaults to XPander. llm_credentials: Direct credential object if not using stored credentials. llm_api_base: Alternative API Base for the LLM. llm_extra_headers: Extra headers to be set to LLM Requests.
          - `model_provider` 'openai' | 'nim' | 'amazon_bedrock' | 'azure_ai_foundary' | 'huggingFace' | 'friendlyAI' | 'anthropic' | 'gemini' | 'fireworks' | 'google_ai_studio' | 'helicone' | 'bytedance' | 'tzafon_lightcone' | 'cerebras' | 'open_router' | 'nebius' | 'cloudflare_ai_gw' | 'z_ai'
          - `model_name` string, nullable
          - `llm_credentials_key` string, nullable
          - `llm_credentials_key_type` 'xpander' | 'custom'
          - `llm_credentials` LLMCredentials
            - `name` string, required
            - `description` string, nullable
            - `value` string, required
          - `llm_api_base` string, nullable
          - `llm_extra_headers` object, nullable
      - OrchestrationPointerNode: Node that references an external asset (agent, function, or orchestration). Attributes: asset_id: Unique identifier of the asset to execute. type: Type of asset being referenced. output_type: Expected output format. Defaults to Text. output_schema: JSON schema for structured output validation. instructions: Optional instructions for the pointer node (Action only). instructions_mode: Mode to use for pointer node, specifically for agent nodes. ignore_response: Should ignore the node result and proceed with previous result?. persist_thread_id: Should persist the thread in agent nodes? default (True). schema_override: Optional schema override with permanentValue fields for fixed values.
        - `asset_id` string, required
        - `type` 'agent' | 'custom_function' | 'orchestration' | 'action', required
        - `output_type` 'text' | 'markdown' | 'json' | 'voice'
        - `output_schema` object, nullable
        - `instructions` string, nullable
        - `instructions_mode` 'replace' | 'append': Modes for instruction usage in pointer node. Attributes: Replace: Replaces the traget asset instructions. Append: Appends to the traget asset instructions.
        - `ignore_response` boolean, nullable
        - `persist_thread_id` boolean, nullable
        - `schema_override` SchemaOverride: Schema override for workflow action nodes. Allows setting permanent (fixed) values for tool input properties. Fields with permanentValue will be removed from the schema sent to the LLM and the permanent values will be applied to the payload before execution. Attributes: input: Input schema with permanentValue fields to override LLM-generated values.
          - `input` object, nullable
      - OrchestrationWaitNodeOutput: Node that pauses execution until an external event occurs. Attributes: type: Type of wait event (webhook or human-in-the-loop). definition: Notification configuration for triggering continuation.
        - `type` 'webhook' | 'hitl', required
        - `definition` union, required
          - EmailNotificationSettings: Configuration for email notifications. Attributes: to: List of recipient email addresses.
            - `subject` string, nullable
            - `body` string, nullable
            - `approve_button_text` string, nullable
            - `deny_button_text` string, nullable
            - `logo_url` string, nullable
            - `to` string[], required
          - SlackNotificationSettings: Configuration for Slack notifications. Attributes: channels: List of Slack channel IDs or names to post to. connection_id: connector_organization id of a connected Slack workspace. When set and `credentials.access_token` is absent, the delivery path resolves the token server-side from the connection (the client never persists the token). credentials: Slack API authentication credentials. Optional — defaults to empty so a connection_id-only target parses; the token is resolved at send time.
            - `subject` string, nullable
            - `body` string, nullable
            - `approve_button_text` string, nullable
            - `deny_button_text` string, nullable
            - `logo_url` string, nullable
            - `channels` string[], required
            - `connection_id` string, nullable
            - `credentials` SlackCredentials: Slack API authentication credentials. Attributes: authed_user_id: Authenticated user's Slack ID. access_token: OAuth access token for API calls. client_id: Slack app client ID. client_secret: Slack app client secret. verification_token: Token for verifying requests from Slack. signing_secret: Secret for validating webhook signatures. app_configuration_token: Token for app configuration. app_configuration_refresh_token: Refresh token for app configuration.
              - …
          - WebhookNotificationSettings: Configuration for webhook notifications. Attributes: url: Target webhook URL to POST notification data. headers: Optional HTTP headers to include in the webhook request.
            - `subject` string, nullable
            - `body` string, nullable
            - `approve_button_text` string, nullable
            - `deny_button_text` string, nullable
            - `logo_url` string, nullable
            - `url` string, required
            - `headers` object, nullable
      - OrchestrationGuardrailNodeOutput: Node that uses LLM to evaluate input against pass/fail criteria. This node works like a classifier with exactly 2 groups: "pass" and "fail". The user defines evaluation_criteria for each group. Routing behavior: - If guardrail passes: routes to downstream node with condition group_id="pass" - If guardrail fails: routes to downstream node with condition group_id="fail" - If no fail route exists: falls back to end nodes (end-summarizer or end-classifier) - A pass route is REQUIRED; fail route is optional. Attributes: groups: List of 2 ClassificationGroup objects with IDs "pass" and "fail". Each group has evaluation_criteria defined by the user. examples: Example inputs/outputs to guide the LLM behavior. settings: LLM configuration settings.
        - `groups` ClassificationGroup[], required
          - `id` string
          - `name` string, required
          - `evaluation_criteria` string, required
          - `auto_extract_relevant_data` boolean, nullable
          - `data_extraction_keys` string[], nullable
        - `examples` string[], nullable
        - `settings` OrchestrationClassifierNodeLLMSettings, required: LLM configuration for classifier nodes. Attributes: model_provider: The LLM provider to use. Defaults to AmazonBedrock. model_name: Specific model identifier. Defaults to "global.anthropic.claude-opus-5-5". llm_credentials_key: Key identifier for stored credentials. llm_credentials_key_type: Type of credential key storage. Defaults to XPander. llm_credentials: Direct credential object if not using stored credentials. llm_api_base: Alternative API Base for the LLM. llm_extra_headers: Extra headers to be set to LLM Requests.
          - `model_provider` 'openai' | 'nim' | 'amazon_bedrock' | 'azure_ai_foundary' | 'huggingFace' | 'friendlyAI' | 'anthropic' | 'gemini' | 'fireworks' | 'google_ai_studio' | 'helicone' | 'bytedance' | 'tzafon_lightcone' | 'cerebras' | 'open_router' | 'nebius' | 'cloudflare_ai_gw' | 'z_ai'
          - `model_name` string, nullable
          - `llm_credentials_key` string, nullable
          - `llm_credentials_key_type` 'xpander' | 'custom'
          - `llm_credentials` LLMCredentials
            - `name` string, required
            - `description` string, nullable
            - `value` string, required
          - `llm_api_base` string, nullable
          - `llm_extra_headers` object, nullable
      - OrchestrationSummarizerNodeOutput: Node that processes large payloads and answers specific questions. This node uses an LLM to summarize or extract information from large inputs. Attributes: instructions: Summarization or question-answering instructions for the LLM. examples: Example inputs/outputs to guide the LLM behavior. settings: LLM configuration settings.
        - `instructions` string, required
        - `examples` string[], nullable
        - `settings` OrchestrationClassifierNodeLLMSettings, required: LLM configuration for classifier nodes. Attributes: model_provider: The LLM provider to use. Defaults to AmazonBedrock. model_name: Specific model identifier. Defaults to "global.anthropic.claude-opus-5-5". llm_credentials_key: Key identifier for stored credentials. llm_credentials_key_type: Type of credential key storage. Defaults to XPander. llm_credentials: Direct credential object if not using stored credentials. llm_api_base: Alternative API Base for the LLM. llm_extra_headers: Extra headers to be set to LLM Requests.
          - `model_provider` 'openai' | 'nim' | 'amazon_bedrock' | 'azure_ai_foundary' | 'huggingFace' | 'friendlyAI' | 'anthropic' | 'gemini' | 'fireworks' | 'google_ai_studio' | 'helicone' | 'bytedance' | 'tzafon_lightcone' | 'cerebras' | 'open_router' | 'nebius' | 'cloudflare_ai_gw' | 'z_ai'
          - `model_name` string, nullable
          - `llm_credentials_key` string, nullable
          - `llm_credentials_key_type` 'xpander' | 'custom'
          - `llm_credentials` LLMCredentials
            - `name` string, required
            - `description` string, nullable
            - `value` string, required
          - `llm_api_base` string, nullable
          - `llm_extra_headers` object, nullable
      - OrchestrationSendToEndNode: Node that routes execution to end nodes or finishes the workflow. When triggered, this node will: 1. Route to end nodes (end-summarizer, end-classifier) if they exist 2. Finish workflow execution immediately if no end nodes exist Attributes: message: Optional message or reason for finishing the workflow.
        - `message` string, nullable
      - OrchestrationSelfScheduleNode: Node that pauses the workflow and schedules itself to resume at a later time. At runtime the worker's self-schedule executor: 1. LLM-parses ``when`` (free-text like "in 1 hour", "next Monday 9am") into an absolute ISO-8601 ``run_at`` using the current datetime / user timezone. 2. Creates a row in ``ai_agents_self_schedules`` with the current ``task_id`` and ``workflow_next_node = target_node_id``. 3. Pauses the task. When APScheduler fires the row, the same task is re-invoked with ``payload_extension={"workflow_next_node": target_node_id}`` and the worker resumes execution starting from the target node, re-running target + its forward cone and skipping everything outside that cone. ``target_node_id`` may point to ANY node in the orchestration (forward, backward, or sibling). Backward jumps are bounded by ``max_reschedules`` so loops cannot run away. Attributes: when: Free-text schedule expression, parsed by the worker via an LLM. target_node_id: The id of the node to resume at. Must exist in the orchestration; no topological constraint. prompt: Optional instruction appended to the upstream node's result before being sent as the scheduled run's prompt. If both the upstream result and this prompt are empty, the node fails rather than creating an empty row. max_reschedules: Maximum number of times this node may fire during a single task lifecycle. Once reached, the executor falls through and the graph proceeds via ``next_node_ids``. Defaults to 1.
        - `when` string, required
        - `target_node_id` string, required
        - `prompt` string, nullable
        - `max_reschedules` integer
      - OrchestrationNodePointerDefinition: Definition for a NodePointer node that acts as a graph-position jump. A NodePointer jumps execution to another node's position in the graph. At resolution time, the pointer adopts the source node's definition, type, AND next_node_ids — so after executing the source's logic, the flow continues to the source's original downstream targets. The pointer keeps its own id, name, condition, and strategies. Attributes: source_node_id: ID of the node to jump to.
        - `source_node_id` string, required
      - OrchestrationParallelNodeOutput: Node that executes multiple child nodes in parallel. All child nodes receive the same input (the output of the preceding node). When all child nodes complete, their results are combined: - JSON outputs are merged into a single JSON object keyed by node name. - String outputs are concatenated with node name headers. Attributes: nodes: List of child OrchestrationNode objects to execute in parallel. output_type: Expected output format for the combined result. Defaults to Text. output_schema: JSON schema for structured output validation of the combined result. output_instructions: Instructions for transforming the combined output into the schema.
        - `nodes` OrchestrationNodeOutput[], required
        - `output_type` 'text' | 'markdown' | 'json' | 'voice'
        - `output_schema` object, nullable
        - `output_instructions` string, nullable
    - `input_type` 'text' | 'markdown' | 'json' | 'voice'
    - `input_schema` object, nullable
    - `input_instructions` string, nullable
    - `agentic_context_input_instructions` string, nullable
    - `agentic_context_output_instructions` string, nullable
    - `return_this` boolean, nullable
  - `notification_settings` NotificationSettingsOutput: 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.
    - `on_success` object, nullable
    - `on_error` object, nullable
    - `on_budget` object, nullable
  - `task_level_strategies` TaskLevelStrategiesOutput: 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.
    - `retry_strategy` OrchestrationRetryStrategy: Strategy for retrying failed orchestration nodes. Attributes: enabled: Whether retry is enabled for this node. max_retries: Maximum number of retry attempts. Defaults to 3.
      - `enabled` boolean, nullable
      - `max_retries` integer, nullable
    - `iterative_strategy` OrchestrationIterativeStrategyOutput: Strategy for iteratively executing orchestration nodes. Attributes: enabled: Whether iterative execution is enabled. max_iterations: Maximum number of iterations. Defaults to 3. end_condition: Optional condition to stop iteration early.
      - `enabled` boolean, nullable
      - `max_iterations` integer, nullable
      - `end_condition` OrchestrationCondition: Condition for controlling orchestration flow. Attributes: type: Type of condition (regex, contains, else, or comparison operators). term: The pattern or string to match against. Used for 'regex' and 'contains' types. group_id: Optional group ID for group-based classifier routing. When set, routing matches by group ID instead of term matching. path: Path to extract value from input data (e.g., "input.client_id" or "client_id"). Used for comparison operators (equal, not_equal, gt, lt, gte, lte, not_empty). value: Value to compare against. Used with comparison operators. Not required for 'not_empty' type.
        - `type` 'regex' | 'contains' | 'else' | 'equal' | 'not_equal' | 'gt' | 'lt' | 'gte' | 'lte' | 'not_empty', required: Types of conditions for orchestration control flow. Attributes: Regex: Condition based on regular expression matching. Contains: Condition based on substring containment. Else: Fallback condition that always matches (executed when no other conditions match). Equal: Condition based on equality comparison (path == value). NotEqual: Condition based on inequality comparison (path != value). GreaterThan: Condition based on greater than comparison (path > value). LessThan: Condition based on less than comparison (path < value). GreaterThanOrEqual: Condition based on greater than or equal comparison (path >= value). LessThanOrEqual: Condition based on less than or equal comparison (path <= value). NotEmpty: Condition that checks if a path value is not empty/null.
        - `term` string, nullable
        - `group_id` string, nullable
        - `path` string, nullable
        - `value` unknown
    - `stop_strategy` OrchestrationStopStrategyOutput: Strategy for stopping orchestration execution. Attributes: enabled: Whether the stop strategy is enabled. stop_on_failure: Whether to stop the entire orchestration on node failure. stop_on_condition: Optional condition that will stop execution if met.
      - `enabled` boolean, nullable
      - `stop_on_failure` boolean, nullable
      - `stop_on_condition` OrchestrationCondition: Condition for controlling orchestration flow. Attributes: type: Type of condition (regex, contains, else, or comparison operators). term: The pattern or string to match against. Used for 'regex' and 'contains' types. group_id: Optional group ID for group-based classifier routing. When set, routing matches by group ID instead of term matching. path: Path to extract value from input data (e.g., "input.client_id" or "client_id"). Used for comparison operators (equal, not_equal, gt, lt, gte, lte, not_empty). value: Value to compare against. Used with comparison operators. Not required for 'not_empty' type.
        - `type` 'regex' | 'contains' | 'else' | 'equal' | 'not_equal' | 'gt' | 'lt' | 'gte' | 'lte' | 'not_empty', required: Types of conditions for orchestration control flow. Attributes: Regex: Condition based on regular expression matching. Contains: Condition based on substring containment. Else: Fallback condition that always matches (executed when no other conditions match). Equal: Condition based on equality comparison (path == value). NotEqual: Condition based on inequality comparison (path != value). GreaterThan: Condition based on greater than comparison (path > value). LessThan: Condition based on less than comparison (path < value). GreaterThanOrEqual: Condition based on greater than or equal comparison (path >= value). LessThanOrEqual: Condition based on less than or equal comparison (path <= value). NotEmpty: Condition that checks if a path value is not empty/null.
        - `term` string, nullable
        - `group_id` string, nullable
        - `path` string, nullable
        - `value` unknown
    - `max_runs_per_day` integer, nullable
    - `agentic_context_enabled` boolean, nullable
    - `duplication_prevention` DuplicationPreventionSettings: Settings for preventing duplicate event processing in workflows. When enabled, this prevents the same event from triggering a workflow multiple times within a configured time window. Useful for webhooks from services like Stigg or Cal.com that may fire the same event multiple times. Attributes: enabled: Whether duplication prevention is active. ttl_minutes: Time window to consider events as duplicates (default: 10 minutes). selectors: List of dot-notation paths to extract unique ID components from input. Multiple selectors are combined to form a composite key. Examples: - ["messageId"] - single field - ["input.event_id", "input.user_id"] - composite key - ["triggerEvent", "payload.uid"] - Cal.com style
      - `enabled` boolean, nullable
      - `ttl_minutes` integer, nullable
      - `selectors` string[], required
    - `slackbot_formatting_instructions` string, nullable
    - `budget` BudgetSettingsOutput: Budget configuration embedded in an agent's task_level_strategies.
      - `agent_budgets` AgentBudgetOutput[]
        - `amount_usd` number, required
        - `period` 'daily' | 'weekly' | 'monthly': Recurring window an agent budget resets over.
        - `stop_mode` 'finish_inflight' | 'kill_inflight': How a stop applies to a task that is already running.
        - `thresholds` BudgetThreshold[]
          - `percent` number, required
          - `action` 'warn' | 'stop': What happens when a threshold is crossed. Open set — V2 may add approve/throttle/downgrade.
        - `notify` BudgetNotifyOutput: Per-budget notification overrides; unset falls back to the agent's on_budget settings.
          - `channels` object, nullable
          - `max_notifications_per_period` integer, nullable
      - `task_budget` TaskBudgetOutput: Overall (non-recurring) spend cap for a single task.
        - `amount_usd` number, required
        - `stop_mode` 'finish_inflight' | 'kill_inflight': How a stop applies to a task that is already running.
        - `thresholds` BudgetThreshold[]
          - `percent` number, required
          - `action` 'warn' | 'stop': What happens when a threshold is crossed. Open set — V2 may add approve/throttle/downgrade.
        - `notify` BudgetNotifyOutput: Per-budget notification overrides; unset falls back to the agent's on_budget settings.
          - `channels` object, nullable
          - `max_notifications_per_period` integer, nullable
  - `use_oidc_pre_auth` boolean, nullable
  - `pre_auth_audiences` string[], nullable
  - `use_oidc_pre_auth_token_for_llm` boolean, nullable
  - `oidc_pre_auth_token_llm_audience` string, nullable
  - `oidc_pre_auth_token_mcp_audience` string, nullable
  - `can_self_schedule` boolean, nullable
  - `can_archive_conversations` boolean, nullable
  - `max_self_schedules` integer, nullable
  - `use_dynamic_tools` boolean, nullable
  - `workspace_tools_enabled` boolean, nullable
  - `live_surface_sharing_enabled` boolean, nullable
  - `direct_messages` AgentDirectMessages
    - `enabled` boolean
    - `channels` DirectMessageChannel[]
      - `channel` 'slack' | 'whatsapp' | 'telegram' | 'email', required
      - `enabled` boolean
    - `mode` 'first_available' | 'all_selected'
    - `recipients` DirectMessageRecipients
      - `scope` 'listed' | 'org'
      - `user_ids` string[]
      - `group_ids` string[]
  - `slack_settings` AgentSlackSettings
    - `enabled` boolean
    - `send_as` 'user' | 'agent' | 'selected_user'
    - `selected_user_id` string, nullable
    - `dms_enabled` boolean
    - `channel_scope` 'any' | 'listed'
    - `allowed_channels` SlackAllowedChannel[]
      - `id` string, required
      - `name` string
    - `approve_first_contact` boolean
    - `daily_limit` integer
  - `personal_plan` AgentPersonalPlan: 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.
    - `user_id` string, required
    - `plan` 'claude' | 'chatgpt', required
    - `account` string, nullable
    - `on_unavailable` 'fallback' | 'wait' | 'stop', nullable
  - `is_autonomous` boolean, nullable
  - `discoverable` boolean, nullable
  - `task_callers` AgentTaskCallers
    - `scope` 'org' | 'listed' | 'none'
    - `agent_ids` string[]
    - `updated_by` string, nullable
    - `updated_at` string, nullable
  - `conversation_retention` AgentConversationRetention
  - `with_auto_context_management` boolean, nullable
  - `developer_access` boolean, nullable
  - `should_stage_before_publish` boolean, nullable
  - `webhook_url` string, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/xpander/apis/xpander-ai-api-service.md) - [All operations](https://skmtc.dev/xpander/apis/xpander-ai-api-service/llms.txt) - [OpenAPI document](https://skmtc.dev/xpander/apis/xpander-ai-api-service/revisions/4389ec0875d0?raw)