Skip to main content
The Agent Management API provides endpoints for full agent lifecycle management, including creation, messaging, session management, and deletion.

​
List Agents

Get a list of all agents in the system. 
GET /api/agents

​
Response

​
agents
array
Array of agent objects with their configurations.

​
Example

curl -X GET http://localhost:3111/api/agents \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Create Agent

Create a new agent with a custom configuration. 
POST /api/agents

​
Request

​
name
string
required
The name of the agent.
​
description
string
A description of the agent’s purpose.
​
model
string
default:"claude-sonnet-4-6"
The LLM model to use for this agent.
​
systemPrompt
string
System prompt that defines the agent’s behavior and personality.
​
tools
array
Array of tool IDs that the agent can use. Defaults to the agent’s tool profile.
​
toolProfile
string
default:"chat"
Tool profile preset: chat, code, research, ops, data, or full.
​
capabilities
array
Array of capability strings for RBAC enforcement.
​
temperature
number
Sampling temperature (0-2).
​
maxTokens
number
Maximum tokens for agent responses.

​
Response

​
id
string
The unique identifier for the created agent.

​
Example

curl -X POST http://localhost:3111/api/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "research-assistant",
    "description": "Agent specialized in research tasks",
    "model": "gpt-4o",
    "systemPrompt": "You are a research assistant that helps find and analyze information.",
    "toolProfile": "research"
  }'

​
Get Agent

Retrieve details about a specific agent. 
GET /api/agents/:id

​
Path Parameters

​
id
string
required
The unique identifier of the agent.

​
Response

Returns the agent object with full configuration.

​
Example

curl -X GET http://localhost:3111/api/agents/agent-123 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Send Message to Agent

Send a message to a specific agent and get a response. 
POST /api/agents/:id/message

​
Path Parameters

​
id
string
required
The unique identifier of the agent.

​
Request

​
message
string
required
The message to send to the agent.
​
sessionId
string
Optional session ID for conversation continuity. If not provided, a new session is created.

​
Response

​
content
string
The agent’s response message.
​
model
string
The model used for the response.
​
usage
object
Token usage statistics.

​
Example

curl -X POST http://localhost:3111/api/agents/agent-123/message \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Search for recent AI research papers",
    "sessionId": "session-456"
  }'

​
List Agent Sessions

Get all sessions for a specific agent. 
GET /api/agents/:id/sessions

​
Path Parameters

​
id
string
required
The unique identifier of the agent.

​
Response

​
sessions
array
Array of session objects containing session IDs and metadata.

​
Example

curl -X GET http://localhost:3111/api/agents/agent-123/sessions \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Query Agent Memory

Search an agent’s memory for relevant information. 
POST /api/agents/:id/memory

​
Path Parameters

​
id
string
required
The unique identifier of the agent.

​
Request

​
query
string
required
The search query for memory recall.
​
limit
number
default:10
Maximum number of results to return (1-200).

​
Response

​
results
array
Array of memory entries matching the query.

​
Example

curl -X POST http://localhost:3111/api/agents/agent-123/memory \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "research papers",
    "limit": 5
  }'

​
Delete Agent

Permanently delete an agent and all associated data. 
DELETE /api/agents/:id

​
Path Parameters

​
id
string
required
The unique identifier of the agent to delete.

​
Response

Returns 204 No Content on success.

​
Example

curl -X DELETE http://localhost:3111/api/agents/agent-123 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Tool Profiles

When creating agents, you can specify a tool profile to filter available tools:
  • chat: Web search, fetch, memory operations (4 tools)
  • code: File operations, shell execution, code analysis, patch application
  • research: Web operations, browser automation, memory
  • ops: Shell execution, system info, process management, disk/network monitoring
  • data: JSON, CSV, YAML operations, regex, file operations
  • full: All 60+ tools

​
Rate Limiting

  • List/Get operations: 200 requests/hour
  • Create/Delete operations: 100 requests/hour
  • Message operations: 60 requests/hour
  • Memory queries: 200 requests/hour

Build docs developers (and LLMs) love

Get started for freeTalk to us