v2

OpenAPI 3.0.02026-08-051996591.2 MB

Agents

Update agent

Updates part of an agent's configuration, including its tools, instructions, model parameters, and metadata. Fields omitted from the request keep their current values.

patch/v2/agents/{agent_key}

Path parameters

agent_keystring required

A unique key that identifies an agent.

Example:customer_support

The unique key of the agent to update.

Headers

Request-Timeoutinteger

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

Request-Timeout-Millisinteger

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

Request body

namestring

The human-readable name of an agent.

descriptionstring nullable

A detailed description of the agent's purpose and capabilities. Set to null to clear.

tool_configurationsobject nullable

A map of tool configurations available to the agent. Set to null to clear all tools. A map value set to null deletes that tool configuration.

skillsobject nullable

A map of skills available to the agent. Set to null to clear all skills. A map value set to null deletes that skill.

first_step_namestring

Reassign the entry point to an existing step by name. This is the preferred way to change the entry point. The named step must exist in the steps map.

metadataobject nullable

Arbitrary metadata associated with the agent. Set to null to clear.

enabledboolean nullable

Whether the agent is enabled. Set to null to reset to default (true).

stepsobject nullable

A map of additional named steps keyed by step name for partial update. Only provided keys are modified; missing keys are preserved. Set a key's value to null to delete that step.

Example request

{
  "name": "Customer Support Agent",
  "description": "An enhanced AI agent specialized in handling customer support inquiries.",
  "tool_configurations": {
    "customer_search": {
      "type": "corpora_search",
      "argument_override": {
        "query": "customer support documentation"
      }
    }
  },
  "model": {
    "name": "gpt-4",
    "parameters": {
      "temperature": 0.7,
      "max_tokens": 1000,
      "top_p": 0.9
    },
    "retry_configuration": {
      "enabled": true,
      "max_retries": 3,
      "initial_backoff_ms": 1000,
      "max_backoff_ms": 30000,
      "backoff_factor": 2
    }
  },
  "first_step": {
    "instructions": [
      {
        "id": "ins_customer_support_init",
        "version": 1
      }
    ],
    "output_parser": {
      "type": "default"
    },
    "reminders": [
      {
        "type": "templated",
        "template_type": "velocity",
        "template": "You are an expert customer support agent for $agent.name. Available tools: #foreach($tool in $tools)${tool.name}#if($foreach.hasNext), #end#end",
        "hooks": [
          "tool_output"
        ],
        "fire_every": 3,
        "skip_first": 2
      }
    ],
    "next_steps": [
      {
        "condition": "get('$.output.intent') == 'sales'",
        "step_name": "sales_handler"
      }
    ]
  },
  "metadata": {
    "department": "customer_service",
    "version": "1.1.0",
    "owner": "support-team",
    "last_reviewed": "2024-01-15"
  },
  "enabled": true,
  "compaction": {
    "enabled": true,
    "threshold_percent": 80,
    "keep_recent_inputs": 1
  },
  "tool_output_offloading": {
    "enabled": true,
    "mode": "artifact",
    "context_percentage": 0.25,
    "max_threshold_bytes": 1048576,
    "min_threshold_bytes": 4096,
    "headroom_percentage": 0.7
  },
  "steps": {
    "sales_handler": {
      "instructions": [
        {
          "type": "inline",
          "template": "Handle sales inquiries"
        }
      ]
    }
  }
}

Response

The complete updated agent configuration, including the new updated_at timestamp.

keystring required

A unique key that identifies an agent.

namestring required

The human-readable name of an agent.

descriptionstring

A detailed description of the agent's purpose and capabilities.

tool_configurationsobject required

A map of tool configurations available to the agent. The key is the name of the tool configuration and the value is an agent tool configuration.

skillsobject

A map of skills available to the agent, keyed by skill name. Skills provide specialized instructions that can be invoked during agent execution. The skill list (name + description) is shown in the system message; content is loaded on invocation.

first_step_namestring

The name of the agent's entry point step. References a key in the steps map. Matches first_step.name.

stepsobject

A map of named steps keyed by step name. Steps can transition to other steps defined here via next_steps. The entry point is the step named by first_step_name.

metadataobject

Arbitrary metadata associated with the agent for customization and configuration.

enabledboolean required

Whether the agent is currently enabled and available for use.

created_atstring date-time

Timestamp when the agent was created.

updated_atstring date-time

Timestamp when the agent was last updated.

Example response

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