Skip to main content
Version: 2.0

Update Agent API Definition

The Update Agent API enables you to modify an existing AI agent's configuration, including tool assignments, behavioral instructions, model parameters, and operational metadata. This API supports agile agent development and operational management by allowing incremental updates without requiring complete agent recreation or disrupting existing agent sessions.

Organizations use this API to evolve agent capabilities over time, adding new tools as they become available, refining behavioral instructions based on user feedback, adjusting model parameters for optimal performance, and updating metadata for better organization and governance across their agent ecosystem.

Update Agent Request and Response​

To update an agent, send a PATCH request to /v2/agents/{agent_key}. You specify the agent identifier in the URL path and include only the fields you want to modify in the request body:

  • agent_key (string, required): Unique agent identifier in the URL path following pattern agt_[0-9a-zA-Z_-]+$
  • name (string, optional): Updated human-readable agent name
  • description (string, optional): Updated description of agent purpose and capabilities
  • tools (object, optional): Updated tool configuration object
    • available (array, required if tools object provided): Complete list of available tools
      • id (string, required): Tool identifier following pattern tol_.*
      • argument_bindings (object, optional): Fixed arguments for tool execution
    • mode (string, optional): Tool interaction mode (native or instruction)
  • model (object, optional): Updated model configuration
    • name (string, required if model object provided): Model name
    • parameters (object, optional): Model-specific parameters
  • first_step (object, optional): Updated execution step configuration
    • type (string, required if first_step provided): Step type (must be conversational)
    • instructions (array, required if first_step provided): Updated list of instruction objects
    • output_parser (object, required if first_step provided): Output parser configuration
  • metadata (object, optional): Updated metadata (replaces existing metadata completely)
  • enabled (boolean, optional): Updated enabled status

The response includes the complete updated agent configuration with the new updated_at timestamp reflecting when the changes were applied.

Example Request​

UPDATE AGENT REQUEST
1

Example Response​

UPDATE AGENT RESPONSE
1