Agents API

Create, configure, and manage AI agents programmatically. The Agents API provides full CRUD operations plus execution and monitoring capabilities.

Base URL

https://api.faosx.ai/v1/agents

Agent Object

The agent object represents an AI agent instance in your workspace.

interface Agent {
  id: string;                    // Unique identifier (e.g., "agt_abc123")
  workspace_id: string;          // Parent workspace
  name: string;                  // Display name
  description?: string;          // Optional description
  type: AgentType;              // Template or custom
  ontology: string;             // Industry ontology (e.g., "fintech-v1")
  autonomy_level: AutonomyLevel; // L1, L2, L3, or L4
  status: AgentStatus;          // active, paused, training

  // Configuration
  capabilities: Capability[];    // What the agent can do
  guardrails: Guardrails;       // Safety constraints
  personality: Personality;      // Communication style

  // Metadata
  created_at: string;           // ISO 8601 timestamp
  updated_at: string;
  last_active_at: string;

  // Statistics
  stats: {
    total_interactions: number;
    success_rate: number;
    avg_response_time_ms: number;
  };
}

type AutonomyLevel = "L1" | "L2" | "L3" | "L4";
type AgentStatus = "active" | "paused" | "training" | "archived";
type AgentType = "customer-service" | "operations" | "research" | "sales" | "custom";

Create Agent

Create a new agent in your workspace.

POST /v1/agents

Request Body

{
  "name": "Customer Support Agent",
  "description": "Handles customer inquiries and support tickets",
  "type": "customer-service",
  "ontology": "retail-v1",
  "autonomy_level": "L2",

  "capabilities": {
    "customer_inquiry": true,
    "ticket_management": true,
    "order_lookup": true,
    "refund_processing": true
  },

  "guardrails": {
    "require_approval_for": [
      "refund_above_100",
      "account_modifications"
    ],
    "blocked_actions": [
      "share_payment_info",
      "make_promises_not_in_policy"
    ],
    "rate_limits": {
      "actions_per_hour": 100
    }
  },

  "personality": {
    "tone": "friendly-professional",
    "response_length": "concise",
    "empathy_level": "high"
  }
}

Response

{
  "data": {
    "id": "agt_abc123",
    "workspace_id": "ws_xyz789",
    "name": "Customer Support Agent",
    "description": "Handles customer inquiries and support tickets",
    "type": "customer-service",
    "ontology": "retail-v1",
    "autonomy_level": "L2",
    "status": "training",

    "capabilities": {
      "customer_inquiry": true,
      "ticket_management": true,
      "order_lookup": true,
      "refund_processing": true
    },

    "guardrails": {
      "require_approval_for": [
        "refund_above_100",
        "account_modifications"
      ],
      "blocked_actions": [
        "share_payment_info",
        "make_promises_not_in_policy"
      ],
      "rate_limits": {
        "actions_per_hour": 100
      }
    },

    "personality": {
      "tone": "friendly-professional",
      "response_length": "concise",
      "empathy_level": "high"
    },

    "created_at": "2025-12-21T10:00:00Z",
    "updated_at": "2025-12-21T10:00:00Z",
    "last_active_at": null,

    "stats": {
      "total_interactions": 0,
      "success_rate": 0,
      "avg_response_time_ms": 0
    }
  }
}

Autonomy Levels

Level	Name	Behavior	Best For
L1	Assisted	Agent suggests, human executes	New agents, high-risk tasks
L2	Supervised	Agent executes, human approves first	Default recommendation
L3	Autonomous	Agent executes within guardrails	Proven routine tasks
L4	Proactive	Agent anticipates and acts	Advanced, high-trust scenarios

Retrieve Agent

Get details of a specific agent.

GET /v1/agents/{agent_id}

Example Request

curl https://api.faosx.ai/v1/agents/agt_abc123 \
  -H "Authorization: Bearer sk_live_abc123..."

Response

{
  "data": {
    "id": "agt_abc123",
    "workspace_id": "ws_xyz789",
    "name": "Customer Support Agent",
    "status": "active",
    ...
  }
}

List Agents

List all agents in your workspace with optional filtering.

GET /v1/agents

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status: `active`, `paused`, `training`
`type`	string	Filter by type: `customer-service`, `operations`, etc.
`limit`	integer	Results per page (default: 20, max: 100)
`starting_after`	string	Cursor for pagination

Example Request

curl "https://api.faosx.ai/v1/agents?status=active&limit=10" \
  -H "Authorization: Bearer sk_live_abc123..."

Response

{
  "data": [
    {
      "id": "agt_abc123",
      "name": "Customer Support Agent",
      "status": "active",
      ...
    },
    {
      "id": "agt_def456",
      "name": "Sales Assistant",
      "status": "active",
      ...
    }
  ],
  "has_more": false,
  "total_count": 2
}

Update Agent

Update an existing agent's configuration.

PATCH /v1/agents/{agent_id}

Request Body

Only include fields you want to update:

{
  "autonomy_level": "L3",
  "guardrails": {
    "require_approval_for": [
      "refund_above_200"
    ]
  }
}

Response

Returns the updated agent object.

Delete Agent

Delete an agent. This action is irreversible.

DELETE /v1/agents/{agent_id}

Example Request

curl -X DELETE https://api.faosx.ai/v1/agents/agt_abc123 \
  -H "Authorization: Bearer sk_live_abc123..."

Response

{
  "data": {
    "id": "agt_abc123",
    "deleted": true
  }
}

Execute Agent Action

Send a message or task to an agent for execution.

POST /v1/agents/{agent_id}/execute

Request Body

{
  "input": "Customer is asking about order #12345 status",
  "context": {
    "customer_id": "cus_abc123",
    "channel": "email",
    "priority": "normal"
  },
  "wait_for_completion": true
}

Parameters

Parameter	Type	Required	Description
`input`	string	Yes	The message or task
`context`	object	No	Additional context
`wait_for_completion`	boolean	No	Wait for result (default: false)

Synchronous Response (wait_for_completion: true)

{
  "data": {
    "execution_id": "exec_abc123",
    "agent_id": "agt_abc123",
    "status": "completed",
    "result": {
      "action": "order_lookup",
      "output": "Order #12345 shipped on Dec 19, tracking: 1Z999AA10123456784",
      "confidence": 0.95
    },
    "execution_time_ms": 342,
    "created_at": "2025-12-21T10:30:00Z",
    "completed_at": "2025-12-21T10:30:00.342Z"
  }
}

Asynchronous Response (wait_for_completion: false)

{
  "data": {
    "execution_id": "exec_abc123",
    "agent_id": "agt_abc123",
    "status": "processing",
    "created_at": "2025-12-21T10:30:00Z"
  }
}

Use Get Execution Status to check progress.

Get Execution Status

Check the status of an asynchronous execution.

GET /v1/agents/{agent_id}/executions/{execution_id}

Response

{
  "data": {
    "execution_id": "exec_abc123",
    "agent_id": "agt_abc123",
    "status": "completed",
    "result": {
      "action": "order_lookup",
      "output": "Order #12345 shipped on Dec 19",
      "confidence": 0.95
    },
    "execution_time_ms": 342,
    "created_at": "2025-12-21T10:30:00Z",
    "completed_at": "2025-12-21T10:30:00.342Z"
  }
}

Execution Statuses

Status	Description
`processing`	Agent is working on the task
`awaiting_approval`	Requires human approval (L2 autonomy)
`completed`	Successfully finished
`failed`	Execution failed
`cancelled`	Manually cancelled

Approve Pending Action

Approve or reject an action awaiting approval (L2 autonomy).

POST /v1/agents/{agent_id}/executions/{execution_id}/approve

Request Body

{
  "decision": "approve",
  "notes": "Amount is within policy, approved"
}

Parameters

Parameter	Type	Required	Description
`decision`	string	Yes	`approve` or `reject`
`notes`	string	No	Optional explanation

Agent Analytics

Get performance analytics for an agent.

GET /v1/agents/{agent_id}/analytics

Query Parameters

Parameter	Type	Description
`period`	string	Time period: `1d`, `7d`, `30d`, `90d` (default: `7d`)
`metrics`	string	Comma-separated metrics to include

Response

{
  "data": {
    "agent_id": "agt_abc123",
    "period": "7d",
    "metrics": {
      "total_interactions": 487,
      "success_rate": 0.94,
      "avg_response_time_ms": 286,
      "escalation_rate": 0.12,
      "customer_satisfaction": 4.6,

      "actions_by_type": {
        "order_lookup": 245,
        "refund_processing": 89,
        "general_inquiry": 153
      },

      "autonomy_performance": {
        "l2_approval_rate": 0.98,
        "l3_success_rate": 0.96
      }
    }
  }
}

Training & Knowledge

Upload knowledge documents for an agent.

POST /v1/agents/{agent_id}/knowledge

Request Body (multipart/form-data)

curl -X POST https://api.faosx.ai/v1/agents/agt_abc123/knowledge \
  -H "Authorization: Bearer sk_live_abc123..." \
  -F "file=@faq.pdf" \
  -F "type=faq" \
  -F "description=Customer FAQ document"

Parameters

Parameter	Type	Required	Description
`file`	file	Yes	Document (PDF, MD, TXT, DOCX)
`type`	string	Yes	`faq`, `policy`, `product_info`, `template`
`description`	string	No	Document description

Code Examples

TypeScript/JavaScript

import { FAOS } from '@faosx/sdk';

const faos = new FAOS('sk_live_abc123...');

// Create agent
const agent = await faos.agents.create({
  name: 'Support Agent',
  type: 'customer-service',
  ontology: 'retail-v1',
  autonomy_level: 'L2'
});

// Execute action
const result = await faos.agents.execute(agent.id, {
  input: 'Check order #12345 status',
  wait_for_completion: true
});

console.log(result.output);

Python

from faosx import FAOS

faos = FAOS('sk_live_abc123...')

# Create agent
agent = faos.agents.create(
    name='Support Agent',
    type='customer-service',
    ontology='retail-v1',
    autonomy_level='L2'
)

# Execute action
result = faos.agents.execute(
    agent.id,
    input='Check order #12345 status',
    wait_for_completion=True
)

print(result.output)

cURL

# Create agent
curl -X POST https://api.faosx.ai/v1/agents \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "type": "customer-service",
    "ontology": "retail-v1",
    "autonomy_level": "L2"
  }'

# Execute action
curl -X POST https://api.faosx.ai/v1/agents/agt_abc123/execute \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Check order #12345 status",
    "wait_for_completion": true
  }'

Webhooks

Subscribe to agent events:

agent.created
agent.updated
agent.deleted
agent.execution.started
agent.execution.completed
agent.execution.failed
agent.execution.awaiting_approval

See Webhooks API for details.

Errors

Common agent-specific errors:

Error Code	HTTP Status	Description
`agent_not_found`	404	Agent ID doesn't exist
`invalid_autonomy_level`	400	Invalid autonomy level
`guardrail_violation`	403	Action blocked by guardrails
`execution_timeout`	408	Execution exceeded timeout
`agent_not_active`	409	Agent is paused or training

See Error Reference for all error codes.

Rate Limits

Endpoint	Limit
Create Agent	10/hour
Execute Agent	100/minute per agent
All other endpoints	60/minute

See API Overview for details.

Next Steps

Workflows API - Automate multi-step processes
Webhooks - Real-time event notifications
Error Reference - Complete error documentation

Base URL​

Agent Object​

Create Agent​

Request Body​

Response​

Autonomy Levels​

Retrieve Agent​

Example Request​

Response​

List Agents​

Query Parameters​

Example Request​

Response​

Update Agent​

Request Body​

Response​

Delete Agent​

Example Request​

Response​

Execute Agent Action​

Request Body​

Parameters​

Synchronous Response (wait_for_completion: true)​

Asynchronous Response (wait_for_completion: false)​

Get Execution Status​

Response​

Execution Statuses​

Approve Pending Action​

Request Body​

Parameters​

Agent Analytics​

Query Parameters​

Response​

Training & Knowledge​

Request Body (multipart/form-data)​

Parameters​

Code Examples​

TypeScript/JavaScript​

Python​

cURL​

Webhooks​

Errors​

Rate Limits​

Next Steps​

Base URL

Agent Object

Create Agent

Request Body

Response

Autonomy Levels

Retrieve Agent

Example Request

Response

List Agents

Query Parameters

Example Request

Response

Update Agent

Request Body

Response

Delete Agent

Example Request

Response

Execute Agent Action

Request Body

Parameters

Synchronous Response (wait_for_completion: true)

Asynchronous Response (wait_for_completion: false)

Get Execution Status

Response

Execution Statuses

Approve Pending Action

Request Body

Parameters

Agent Analytics

Query Parameters

Response

Training & Knowledge

Request Body (multipart/form-data)

Parameters

Code Examples

TypeScript/JavaScript

Python

cURL

Webhooks

Errors

Rate Limits

Next Steps