API Reference

Functional Agents

Functional agents execute specific tasks and return structured data according to predefined schemas. Perfect for automation, data processing, and API orchestration.

Execute Agent

POST/v1/execute

Execute a functional agent with input parameters and receive structured output.

Request Headers

bash

X-API-Key: YOUR_API_KEY
X-Backend-Token: YOUR_BACKEND_TOKEN (optional)

Request Body

json

{
  "agentId": "agent_abc123",
  "environmentId": "env_xyz789",
  "userContext": "Process a new customer order for premium customer",
  "inputParameters": {
    "customerEmail": "customer@example.com",
    "items": [
      {"productId": "prod_123", "quantity": 2},
      {"productId": "prod_456", "quantity": 1}
    ],
    "shippingAddress": {
      "street": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102"
    },
    "paymentMethodId": "pm_xyz789"
  },
  "customerId": "customer_abc123"
}

Response

json

{
  "data": {
    "orderId": "order_789xyz",
    "status": "confirmed",
    "totalAmount": 189.97,
    "items": [
      {
        "productId": "prod_123",
        "quantity": 2,
        "price": 59.99,
        "subtotal": 119.98
      },
      {
        "productId": "prod_456",
        "quantity": 1,
        "price": 69.99,
        "subtotal": 69.99
      }
    ],
    "estimatedDelivery": "2025-01-15"
  },
  "agentId": "agent_abc123",
  "agentName": "Order Processing Agent",
  "executionTime": 1450,
  "toolsUsed": 4,
  "suggestedActions": [
    {
      "title": "Send Order Confirmation",
      "description": "Send confirmation email to customer",
      "action": "sendEmail",
      "parameters": {
        "to": "customer@example.com",
        "templateId": "order-confirmation",
        "orderId": "order_789xyz"
      }
    }
  ],
  "successUrl": "https://yourapp.com/orders/order_789xyz"
}

Response Fields

Field	Type	Description
`data`	object	Structured output matching agent's output schema Structured output matching agent's output schema
`agentId`	string	ID of the executed agent
`agentName`	string	Name of the executed agent
`executionTime`	number	Execution time in milliseconds
`toolsUsed`	number	Number of actions/APIs called during execution
`suggestedActions`	array (optional)	AI-generated follow-up actions (for mutation operations like create, update, delete)
`successUrl`	string (optional)	URL to redirect users after successful execution (e.g., view created resource)

Suggested Actions: When functional agents perform mutation operations (creating, updating, or deleting resources), they automatically generate intelligent next-step suggestions. Use these to provide users with contextual follow-up actions like sending notifications, viewing results, or triggering related workflows.

The successUrl field provides a direct link to view or interact with the resource created or modified by the agent, enabling seamless navigation after task completion.

Key Features

Structured Output

Agents return data matching your predefined JSON schema, ensuring consistent, type-safe responses.

Multi-step Execution

Agents can perform complex workflows involving multiple API calls, data transformations, and business logic.

Smart Filtering

Automatic response optimization for large datasets—agents intelligently filter and summarize results.

Tool Integration

Connect to external APIs and services seamlessly. Agents determine when and how to use available tools.

Example Use Cases

javascript

// Order Processing Agent
const orderResult = await executeAgent('order-agent', {
  userContext: 'Process new order',
  inputParameters: {
    customerEmail: 'customer@example.com',
    items: [{productId: 'prod_123', quantity: 2}]
  }
});

// Data Extraction Agent
const extractedData = await executeAgent('extraction-agent', {
  userContext: 'Extract invoice data',
  inputParameters: {
    documentUrl: 'https://example.com/invoice.pdf'
  }
});

// Report Generation Agent
const report = await executeAgent('report-agent', {
  userContext: 'Generate quarterly sales report',
  inputParameters: {
    startDate: '2024-01-01',
    endDate: '2024-03-31',
    region: 'US'
  }
});

PreviousConversational Agents NextWorkflows

Last updated: March 2026Report an issue