A2A Protocol15

Agent Aliases20

Agent Analytics4

Agent Connectors5

Agent End User Sessions6

Agent Identity2

Agent Schedules6

Agent Secrets3

Agent Sessions15

Agents6

API Keys5

Application Clients5

Authentication1

Chats9

Corpora9

CustomerMetrics2

Documents7

Encoders2

Factual Consistency Evaluation1

Generation Presets4

Glossaries8

Hallucination Correctors2

Index3

Instructions7

Jobs2

Large Language Models6

LLM Chat Completions1

Metadata Query1

Pipeline Dead Letters5

Pipeline Runs4

Pipelines7

Queries3

Query History2

Rerankers1

Table Extractors1

Tool Servers6

Tools7

Trusted Token Issuers5

Upload1

Users6

Widgets1

Agents

Replace agent

Replaces the complete configuration of an existing agent, including its steps, instructions, tool configurations, and model. Unlike Update agent, which changes only the fields in the request, this operation replaces the whole agent definition.

put/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 replace.

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

keystring

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 the AgentToolConfiguration.

skillsobject

A map of skills available to the agent, keyed by skill name. Skills provide specialized instructions that can be invoked during agent execution.

first_step_namestring

Name of a step in the steps map to use as the entry point. This is the preferred way to define the entry point - define all steps in the steps map and reference the entry point by name here.

stepsobject

A map of named steps keyed by step name. Steps can transition to other steps defined here via next_steps.

metadataobject

Arbitrary metadata associated with the agent for customization and configuration.

enabledboolean

Whether the agent should be enabled upon creation.

created_atstring date-time

Timestamp when the agent was created. Set by the platform; any value provided in the request body is ignored.

updated_atstring date-time

Timestamp when the agent was last updated. Set by the platform on every write; any value provided in the request body is ignored.

Example request

{
  "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.",
      "content": "When reviewing code..."
    }
  },
  "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.0.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"
}

Response

The complete configuration of the replaced agent.

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"
}

Changes

Changed in 1 of the 7 revisions of this API.6446

Aug 5, 2026fca567a46b3a6446See the full diff
- ▲
  the ///////// request property type changed from object to no type
  request-property-type-changed
- ▲
  the ////////// request property type changed from object to no type
  request-property-type-changed
- ▲
  added to the ///// response property oneOf list for the response status
  response-property-one-of-added
- ▲
  added to the ////// response property oneOf list for the response status
  response-property-one-of-added
- ▲
  the ///// response's property type changed from object to no type for status
  response-property-type-changed
- ▲
  the ////// response's property type changed from object to no type for status
  response-property-type-changed
- ●
  removed the request property //////////
  request-property-removed
- ●
  removed the request property //////////
  request-property-removed
- ●
  removed the request property //////////
  request-property-removed
- ●
  removed the request property //////////
  request-property-removed
- ●
  removed the request property //////////
  request-property-removed
- ●
  removed the request property //////////
  request-property-removed
- ●
  removed the request property //////////
  request-property-removed
- ●
  removed the request property //////////
  request-property-removed
- ●
  removed the request property //////////
  request-property-removed
- ●
  removed the request property //////////
  request-property-removed
- ●
  removed the request property //////////
  request-property-removed
- ●
  removed the request property ///////////
  request-property-removed
- ●
  removed the request property ///////////
  request-property-removed
- ●
  removed the request property ///////////
  request-property-removed
- ●
  removed the request property ///////////
  request-property-removed
- ●
  removed the request property ///////////
  request-property-removed
- ●
  removed the request property ///////////
  request-property-removed
- ●
  removed the request property ///////////
  request-property-removed
- ●
  removed the request property ///////////
  request-property-removed
- ●
  removed the request property ///////////
  request-property-removed
- ●
  removed the request property ///////////
  request-property-removed
- ●
  removed the request property ///////////
  request-property-removed
- ●
  removed the optional property ////// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property ////// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property ////// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property ////// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property ////// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property ////// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property ////// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property ////// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property ////// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property ////// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property ////// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property /////// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property /////// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property /////// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property /////// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property /////// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property /////// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property /////// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property /////// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property /////// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property /////// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property /////// from the response with the status
  response-optional-property-removed
- ○
  added discriminator to ///////// request property
  request-property-discriminator-added
- ○
  added discriminator to ////////// request property
  request-property-discriminator-added
- ○
  added to the ///////// request property oneOf list
  request-property-one-of-added
- ○
  added to the ////////// request property oneOf list
  request-property-one-of-added
- ○
  added discriminator to ///// response property for the response status
  response-property-discriminator-added
- ○
  added discriminator to ////// response property for the response status
  response-property-discriminator-added

Full history