Replace Agent API Definition

The Replace Agent API enables you to completely replace an existing agent's configuration, including its corpora, tools, and generation presets. This endpoint performs a full replacement of the agent definition, unlike the Update Agent API which only modifies specified fields.

Endpoint: PUT /v2/agents/{agent_key}

Path Parameters

Parameter	Type	Description
agent_key	string	The unique key of the agent to replace

Request Body

The request body should contain a complete agent definition with all required fields:

REPLACE AGENT REQUEST

Code example with json syntax.json

1

Response

200 - Success

{
  "key": "agt_customer_support_123",
  "name": "updated-customer-support", 
  "description": "Updated customer support agent with new capabilities",
  "tool_configurations": {
    "support_search": {
      "type": "corpora_search",
      "query_configuration": {
        "search": {
          "corpora": [{"corpus_key": "support-docs-v2"}],
          "limit": 5
        }
      }
    },
    "web_search": {
      "type": "web_search",
      "argument_override": {
        "limit": 10
      }
    }
  },
  "first_step": {
    "type": "conversational",
    "instructions": [{
      "type": "inline",
      "name": "inl_support_001",
      "description": "Support assistant instruction",
      "template": "You are a customer support assistant. Always be helpful and search internal docs first.",
      "enabled": true
    }],
    "output_parser": {
      "type": "default"
    }
  },
  "model": {
    "name": "gpt-4",
    "parameters": {
      "temperature": 0.3,
      "max_tokens": 1000
    }
  },
  "metadata": {
    "version": "2.0",
    "team": "support"
  },
  "enabled": true,
  "created_at": "2025-01-14T10:00:00.000Z"
}

400 - Bad Request

{
  "field_errors": {
    "name": "Agent name is required",
    "tool_configurations": "At least one tool configuration is required"
  },
  "request_id": "req_123"
}

404 - Not Found

{
  "message": "Agent not found",
  "request_id": "req_456"
}

403 - Forbidden

{
  "message": "Permissions do not allow replacing this agent",
  "request_id": "req_789"
}

Usage Examples

cURL

REPLACE AGENT WITH CURL

Code example with bash syntax.bash

1

Python

import requests

url = "https://api.vectara.io/v2/agents/agt_customer_support_123"

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "name": "updated-customer-support",
    "description": "Updated customer support agent with new capabilities",
    "tool_configurations": {
        "support_search": {
            "type": "corpora_search",
            "query_configuration": {
                "search": {
                    "corpora": [{"corpus_key": "support-docs-v2"}],
                    "limit": 5
                }
            }
        }
    },
    "first_step": {
        "type": "conversational",
        "instructions": [{
            "type": "inline",
            "name": "Support Assistant",
            "template": "You are a customer support assistant. Always be helpful and search internal docs first."
        }],
        "output_parser": {
            "type": "default"
        }
    },
    "model": {
        "name": "gpt-4",
        "parameters": {
            "temperature": 0.3,
            "max_tokens": 1000
        }
    },
    "enabled": True
}

response = requests.put(url, headers=headers, json=data)
print(response.json())

Difference from Update Agent

• Replace Agent (PUT): Completely replaces the entire agent configuration
• Update Agent (PATCH): Only modifies specified fields, leaving others unchanged

Use Replace Agent when you want to:

• Completely redefine an agent's configuration
• Ensure the agent has only the specified tools and settings
• Reset all fields to new values