Create or Update an Agent using the Agent Builder

POST

/api/v2/agents/agentbuilder

Handle POST requests to create or update an Agent using the Agent Builder.

Staging behaviour:

Pass agent_version=staging as a query parameter to update the staging version of the agent instead of the published agent's.

Request Body:

history: List of past conversation messages, each with a 'role' (e.g., 'user') and 'content'.

agent_id: ID of an existing agent(optional) to update.

project_id: ID of the project to associate the new agent with.

flags (optional dictionary): Feature flags for agent capabilities.

caching_enabled: Whether response caching is enabled for this chat session.

Returns:

Response with the updated agent state if the creation is successful.

Response with an error message if validation fails or an internal error occurs.

Current Version:

2.0.0

Request

Header Params

Body Params

application/json

Required

Examples

Responses

🟢201Created

application/json

Success

Bodyapplication/json

🟠400Bad Request

🟠403Server Error

🔴500

🔴503

Request Example

Shell

JavaScript

Java

Swift

curl --location --globoff 'https:///api/v2/agents/agentbuilder' \
--header 'Organization-Id;' \
--header 'Ocp-Apim-Subscription-Key: ' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
    "history": [
        {
            "role": "user",
            "content": "Hello, how are you?"
        }
    ],
    "agent_id": 1,
    "project_id": 1,
    "flags": {
        "edit": true
    },
    "user_id": 1,
    "caching_enabled": true
}'

Response Example

201 - Sample Response

{
    "success": true,
    "message": "Agent created successfully by Agent Builder",
    "data": {
        "response": "Hello! How can I assist you in building a custom agent today?",
        "history": [
            {
                "role": "user",
                "content": "hi"
            },
            {
                "role": "ai",
                "content": "Hello! How can I assist you in building a custom agent today?"
            }
        ],
        "agent_id": 0,
        "agent_state": {
            "agent_name": "Legal Consultant",
            "prefix_prompt": "You are an AI assistant specializing in providing legal advice on regulatory requirements, compliance issues, and legal barriers to market entry.",
            "agent_image": "/build/static/media/xyz123.png",
            "description": "Legal advisor provides expert guidance on compliance audits, risk assessment, contract management, and regulatory requirements to ensure legal and operational excellence."
        },
        "new_image": false
    }
}

Get all workflows for an agent

Get all Character Voices