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
}