The Agents API allows you to create, manage, and execute AI agents in your application.

​
Create an Agent

​
POST /v1/agents
Create a new AI agent with specified configuration.

​
Request Body

​
name
string
required
The name of the agent
​
instruction
string
required
The system instruction for the agent that defines its behavior
​
model
string
required
The LLM model to use (must be one of the supported models)
​
tool
string
Optional tool integration for the agent
curl -X POST https://www.trytruffle.ai/api/agents \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent",
    "instruction": "You are a helpful customer support agent",
    "model": "gpt-4o-mini",
    "tool": "Tavily Research",
  }'

​
Response

​
agent_id
string
The unique identifier of the created agent
​
created_at
string
ISO 8601 timestamp of when the agent was created
{
    "success": true,
    "data": {
        "agent_id": "agent_123",
        "created_at": "2024-02-07T20:43:00Z"
    },
    "status": 200
}

​
List Agents

​
GET /v1/agents
Retrieve a list of all agents for the authenticated user.

​
Query Parameters

​
pretty
boolean
Whether to pretty-print the JSON response
curl https://www.trytruffle.ai/api/agents \
  -H "x-api-key: YOUR_API_KEY"

​
Response

​
agents
array
List of agent objects
{
    "success": true,
    "data": [
        {
            "agent_id": "agent_123",
            "name": "Customer Support Agent",
            "config": {
                "agent_id": "agent_123",
                "name": "Customer Support Agent",
                "instruction": "You are a helpful customer support agent",
                "model": "gpt-4o-mini",
                "tool": "search"
            },
            "created_at": "2024-02-07T20:43:00Z",
            "updated_at": "2024-02-07T20:43:00Z"
        }
    ],
    "status": 200
}

​
Get Agent Details

​
GET /v1/agents/{agentId}
Retrieve details of a specific agent.

​
Path Parameters

​
agentId
string
required
The unique identifier of the agent

​
Query Parameters

​
pretty
boolean
Whether to pretty-print the JSON response
curl https://www.trytruffle.ai/api/agents/agent_123 \
  -H "x-api-key: YOUR_API_KEY"

​
Response

​
agent
object
The agent details
{
    "success": true,
    "data": {
        "agent_id": "agent_123",
        "name": "Customer Support Agent",
        "config": {
            "agent_id": "agent_123",
            "name": "Customer Support Agent",
            "instruction": "You are a helpful customer support agent",
            "model": "gpt-4o-mini",
            "tool": "search"
        },
        "created_at": "2024-02-07T20:43:00Z",
        "updated_at": "2024-02-07T20:43:00Z"
    },
    "status": 200
}

​
Run Agent

​
POST /v1/agents/{agentId}/run
Execute an agent with the provided input.

​
Path Parameters

​
agentId
string
required
The unique identifier of the agent

​
Request Body

​
input
string
required
The input text for the agent to process
​
session_id
string
Optional session ID for continuing a conversation
curl -X POST https://www.trytruffle.ai/api/agents/agent_123/run \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "How can I help you today?",
    "session_id": "optional_session_123"
  }'

​
Response

​
output
string
The agent’s response to the input
​
session_id
string
The session ID for this conversation
{
    "success": true,
    "data": {
        "output": "I'm here to assist you with any questions or concerns you may have.",
        "session_id": "session_123"
    },
    "status": 200
}