Execute reasoners and skills synchronously and receive results immediately. Agentfield automatically tracks execution metadata, enabling distributed tracing and workflow visualization without manual instrumentation.

Quick Start

Execute any reasoner or skill using the unified execution endpoint:

curl -X POST http://localhost:8080/api/v1/execute/support-agent.analyze_sentiment \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "message": "This is the third time I am calling!",
      "conversation_history": []
    }
  }'

Response:

{
  "execution_id": "exec_abc123",
  "run_id": "run_def456",
  "status": "succeeded",
  "result": {
    "sentiment": "frustrated",
    "confidence": 0.92,
    "recommendation": "escalate"
  },
  "duration_ms": 1247,
  "finished_at": "2024-01-15T10:30:45Z"
}

Calling Router-Organized Functions

If your agent uses AgentRouter to organize functions, the router prefix becomes part of the endpoint:

# Agent code with router
from agentfield.router import AgentRouter

support = AgentRouter(prefix="support")

@support.reasoner()
async def analyze_sentiment(message: str) -> dict:
    """Analyze customer sentiment."""
    return await support.ai(...)

app.include_router(support)  # Registered as: support_analyze_sentiment

API call includes the router prefix:

# Note: "support" prefix is now part of the function name
curl -X POST http://localhost:8080/api/v1/execute/support-agent.support_analyze_sentiment \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "message": "This is the third time I am calling!"
    }
  }'

Without router: support-agent.analyze_sentiment With router prefix "support": support-agent.support_analyze_sentiment

See AgentRouter documentation for details on how prefixes translate to API endpoints.

Endpoint

Examples

# Execute sentiment analysis
curl -X POST http://localhost:8080/api/v1/execute/support-agent.analyze_sentiment \
-H "Content-Type: application/json" \
-H "X-Session-ID: session_user123" \
-H "X-Actor-ID: user_john_doe" \
-d '{
  "input": {
    "message": "This is the third time I am calling about this issue!",
    "conversation_history": [
      {"role": "user", "content": "My order never arrived"},
      {"role": "agent", "content": "Let me check that for you"}
    ]
  }
}'

# Execute sentiment analysiscurl -X POST http://localhost:8080/api/v1/execute/support-agent.analyze_sentiment \-H "Content-Type: application/json" \-H "X-Session-ID: session_user123" \-H "X-Actor-ID: user_john_doe" \-d '{  "input": {    "message": "This is the third time I am calling about this issue!",    "conversation_history": [      {"role": "user", "content": "My order never arrived"},      {"role": "agent", "content": "Let me check that for you"}    ]  }}'

Response Fields

Field	Type	Description
`execution_id`	string	Unique identifier for this execution
`run_id`	string	Workflow run identifier grouping related executions
`status`	string	Execution status: `succeeded`, `failed`
`result`	object	The reasoner/skill output (structure defined by your agent)
`error_message`	string	Error details if status is `failed`
`duration_ms`	number	Execution duration in milliseconds
`finished_at`	string	Completion timestamp (ISO 8601)

Execution Flow

When you execute an agent, Agentfield automatically:

Validates the request against your agent's Pydantic schema
Persists execution metadata for tracing and observability
Routes the request to your agent's HTTP endpoint
Tracks execution duration and status
Returns the result with complete metadata

Under the Hood: Agentfield uses a distributed execution model where each agent runs as an independent service. The control plane orchestrates requests, tracks execution state, and constructs workflow DAGs automatically—no manual instrumentation needed.

Multi-Agent Workflows

Chain multiple agents together using the execution response:

// Step 1: Analyze sentiment
const sentiment = await fetch(
  'http://localhost:8080/api/v1/execute/support-agent.analyze_sentiment',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'X-Workflow-ID': 'wf_123' },
    body: JSON.stringify({
      input: { message: customerMessage }
    })
  }
).then(r => r.json());

// Step 2: Route based on AI decision
if (sentiment.result.recommendation === 'escalate') {
  await fetch(
    'http://localhost:8080/api/v1/execute/escalation-agent.create_ticket',
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json', 'X-Workflow-ID': 'wf_123' },
      body: JSON.stringify({
        input: {
          customer_id: customerId,
          sentiment: sentiment.result,
          priority: 'high'
        }
      })
    }
  );
}

Agentfield automatically links these executions into a workflow DAG using the X-Workflow-ID header.

Error Handling

Handle execution errors gracefully:

import requests

try:
    response = requests.post(
        'http://localhost:8080/api/v1/execute/support-agent.analyze_sentiment',
        json={'input': {'message': 'Help!'}},
        timeout=30
    )
    response.raise_for_status()

    result = response.json()

    if result['status'] == 'failed':
        print(f"Execution failed: {result.get('error_message')}")
    else:
        print(f"Result: {result['result']}")

except requests.exceptions.Timeout:
    print("Execution timed out")
except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")

Best Practices

1. Use Workflow Headers

Always include workflow headers for related executions:

curl -X POST http://localhost:8080/api/v1/execute/agent.reasoner \
  -H "X-Workflow-ID: wf_customer_support_001" \
  -H "X-Session-ID: session_user_456" \
  -H "X-Actor-ID: user_456" \
  -d '{"input": {...}}'

This enables:

Automatic workflow DAG construction
Session-scoped memory access
Actor-based attribution and auditing

2. Handle Timeouts

Set appropriate timeouts for AI operations:

const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 30000); // 30s

try {
  const response = await fetch(url, {
    signal: controller.signal,
    // ... other options
  });
} finally {
  clearTimeout(timeout);
}

3. Validate Input Schemas

Ensure your input matches the agent's Pydantic schema:

# Your agent definition
class SentimentInput(BaseModel):
    message: str
    conversation_history: List[Dict[str, str]] = []

# Valid request
{
  "input": {
    "message": "Help!",
    "conversation_history": [
      {"role": "user", "content": "Previous message"}
    ]
  }
}

Long-Running Tasks

For tasks that take more than a few seconds, use async execution instead:

# Queue long-running task
curl -X POST http://localhost:8080/api/v1/execute/async/research-agent.deep_analysis \
  -H "Content-Type: application/json" \
  -d '{
    "input": {"topic": "market analysis"},
    "webhook": {
      "url": "https://app.example.com/webhooks/agentfield",
      "secret": "your-secret"
    }
  }'

Async Execution - Queue long-running tasks with webhooks
Memory Operations - Share data between agents
Workflow Management - Visualize execution DAGs
Python SDK - Execute agents from Python code

Agent Execution