Skip to main content

​
Agents API

The Agents API allows you to manage autonomous AI agents that execute multi-step tasks. Agents can use tools, handle approvals, and maintain execution state through threads.

​
Capabilities

  • CRUD Operations: Create, read, update, and delete agents
  • Thread Management: Create and manage execution threads
  • Execution Control: Pause, resume, and complete agent executions
  • Approval Workflows: Handle human-in-the-loop approval requests
  • Evaluations: Evaluate agent performance with scoring criteria
  • Cost Tracking: Monitor daily and monthly costs

​
Key Concepts

​
Agent

An agent is configured through an embedded assistantSpecialization object that determines its behavior and capabilities:
PropertyDescription
nameAgent display name
assistantSpecialization.presetsSystem prompt / instructions
assistantSpecialization.availableToolsGroupsUidsTool groups the agent can use
provider / llmLLM configuration
maxExecutionToolCallsMaximum tool calls per execution

​
Thread

A thread represents a single execution of an agent. Threads can be in the following states:
StateDescription
PENDINGCreated, not yet started
PROCESSINGActively executing
WAITING_APPROVALPaused awaiting user approval
PAUSEDManually paused
COMPLETEDFinished successfully
FAILEDEncountered an error

​
Endpoints Summary

​
Agent Management

MethodEndpointDescription
GET/api/v1/agentsList all agents
GET/api/v1/agents/:agentIdGet agent by ID
POST/api/v1/agentsCreate a new agent
PATCH/api/v1/agents/:agentIdUpdate an agent
DELETE/api/v1/agents/:agentIdDelete an agent

​
Thread Management

MethodEndpointDescription
POST/api/v1/agents/:agentId/threadsCreate a new thread
GET/api/v1/agents/:agentId/threadsList threads for an agent
GET/api/v1/agents/threads/:threadIdGet specific thread
POST/api/v1/agents/threads/:threadId/pausePause a thread
POST/api/v1/agents/threads/:threadId/resumeResume a thread
POST/api/v1/agents/threads/:threadId/completeComplete a thread
POST/api/v1/agents/threads/:threadId/approvalHandle approval request

​
Evaluations

MethodEndpointDescription
POST/api/v1/agents/threads/:threadId/evaluateEvaluate a thread
GET/api/v1/agents/threads/:threadId/evaluationsGet all evaluations

​
Cost Tracking

MethodEndpointDescription
GET/api/v1/agents/agents/:agentId/costs/dailyGet daily costs
GET/api/v1/agents/agents/:agentId/costs/monthlyGet monthly costs
GET/api/v1/agents/agents/:agentId/costs/summaryGet cost summary

​
Example: Create an Agent

curl -X POST "https://api.devic.ai/api/v1/agents" \
  -H "Authorization: Bearer devic-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent",
    "description": "Handles customer support tickets",
    "assistantSpecialization": {
      "presets": "You are a customer support agent. Be helpful and professional.",
      "availableToolsGroupsUids": ["support-tools", "crm-tools"],
      "model": "gpt-4o"
    },
    "maxExecutionToolCalls": 30
  }'

​
Example: Create a Thread

curl -X POST "https://api.devic.ai/api/v1/agents/agent-123/threads" \
  -H "Authorization: Bearer devic-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Analyze the Q4 sales report and create a summary",
    "tags": ["sales", "quarterly-report"]
  }'

​
Example: Handle Approval

curl -X POST "https://api.devic.ai/api/v1/agents/threads/thread-456/approval" \
  -H "Authorization: Bearer devic-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "approved": true,
    "message": "Proceed with the data export"
  }'

​
Tool Access

Agents access tools through availableToolsGroupsUids:
  1. Each UID references a Tools Group
  2. Tools Groups can contain built-in tools or reference a Tool Server
  3. When an agent executes, it can call any tool from its assigned groups
  4. Use enabledTools to restrict to a specific subset
Example: An agent with availableToolsGroupsUids: ["crm-tools", "email-tools"] can use all tools from both groups.

​
See Also