Create Agent API Definition

The Create Agent API lets you design and deploy smart AI agents capable of managing sophisticated workflows, running tool-based actions, and also keep conversational context across multi-turn dialogues. Using the Model Context Protocol (MCP), this API enables the development of autonomous digital workers that combine retrieval-augmented generation with external system integration.

By configuring agents with specific tools, behavioral instructions, and model parameters, enterprises can deploy specialized agents for customer support, business intelligence, workflow automation, and technical assistance scenarios. These agents operate as configurable, decision-making entities that can reason through problems, coordinate multiple tools, and adapt their responses based on conversation context and available capabilities.

What is an agent?

An agent is comprised of three main components of functionality:

1. Instructions: Known as a system prompt in other platforms.
2. Steps: The workflow the agent executes.
3. Tools: Resources available to resolve steps and instructions.

To use an agent, create a new session (called a thread or chat in other platforms), and send new inputs to the agent to get responses.

Create Agent Request and Response

To create an agent, send a POST request to /v2/agents. You specify the following parameters in the request body:

• key (string, optional): A user provided key that uniquely identifies this agent. If not provided, one will be auto-generated based on the agent name. Pattern: [0-9a-zA-Z_-]+$
• name (string, required): The human-readable name of the agent
• description (string, optional): Detailed description of agent purpose and capabilities
• tool_configurations (object, required): A map of tool configurations available to the agent where:
  • Key: A user-defined name for the tool configuration (e.g., customer_search)
  • Value: An AgentToolConfiguration object with:
    • type (string, required): Tool configuration type (mcp, corpora_search, or web_search)
    • argument_override (object, optional): Optional hardcoded arguments for tool calls
    • query_configuration (object, required for corpora_search): User-configurable settings for corpus search
• model (object, required): Model configuration for agent reasoning
  • name (string, required): Model name (e.g., gpt-4)
  • parameters (object, optional): Model-specific parameters like temperature and max_tokens
• first_step (object, required): Initial execution step configuration
  • type (string, required): Step type (must be conversational)
  • instructions (array, required): List of instruction objects
    • Reference instructions:
      • type (string, required): Must be reference
      • id (string, required): Instruction identifier following pattern ins_[0-9a-zA-Z_-]+$
      • version (integer, optional): Specific instruction version
    • Inline instructions:
      • type (string, required): Must be inline
      • name (string, required): Human-readable instruction name
      • template_type (string, optional): Must be velocity (default)
      • template (string, required): Instruction template content
      • description (string, optional): Instruction description
  • output_parser (object, required): Output parser configuration
    • type (string, required): Parser type (must be default)
• metadata (object, optional): Arbitrary key-value pairs for organization and tracking
• enabled (boolean, optional): Whether agent is active upon creation (defaults to true)

The response includes the complete agent configuration with system-generated fields including the unique agent key, creation timestamp, and update timestamp.

Example Request

EXAMPLE AGENT REQUESTjson

1

Example Response

EXAMPLE RESPONSEjson

1

Error Responses

The API returns standard HTTP error codes with detailed error information:

HTTP Code	Error Code	Description
400	invalid_request	Missing required fields or malformed request structure
400	invalid_tool_reference	Referenced tool does not exist or is inaccessible
400	invalid_instruction_reference	Referenced instruction does not exist or is inaccessible
400	invalid_model_configuration	Invalid model name or unsupported parameters
401	unauthorized	Invalid or missing API key
403	forbidden	Insufficient permissions for agent creation
429	rate_limit_exceeded	Agent creation rate limit exceeded