The Agents API allows you to create, manage, and execute AI agents in your application.
Create an Agent
Create a new AI agent with specified configuration.
Request Body
The system instruction for the agent that defines its behavior
The LLM model to use (must be one of the supported models)
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
The unique identifier of the created agent
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
Retrieve a list of all agents for the authenticated user.
Query Parameters
Whether to pretty-print the JSON response
curl https://www.trytruffle.ai/api/agents \
-H "x-api-key: YOUR_API_KEY"
Response
{
"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
Retrieve details of a specific agent.
Path Parameters
The unique identifier of the agent
Query Parameters
Whether to pretty-print the JSON response
curl https://www.trytruffle.ai/api/agents/agent_123 \
-H "x-api-key: YOUR_API_KEY"
Response
{
"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
The unique identifier of the agent
Request Body
The input text for the agent to process
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
The agent’s response to the input
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
}
