​
POST /v1/agents/{agent_id}/invoke

Invoke an agent and receive a synchronous response.

​
Request

POST https://api.run-agent.ai/v1/agents/{agent_id}/invoke
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

​
Path Parameters

​
agent_id
string
required
The unique identifier of the agent to invoke

​
Request Body

​
query
string
required
The input query or prompt for the agent
​
parameters
object
Additional parameters for the agent
​
session_id
string
Session ID for maintaining conversation context

​
Response

​
result
object
required
The agent’s response
​
usage
object
Token usage information
​
metadata
object
Additional metadata

​
Examples

​
Basic Invocation

curl -X POST https://api.run-agent.ai/v1/agents/agent-123/invoke \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the weather like in San Francisco?"
  }'

​
With Parameters

{
  "query": "Write a story about AI",
  "parameters": {
    "temperature": 0.8,
    "max_tokens": 500,
    "style": "science fiction"
  },
  "session_id": "user-123-session"
}

​
Response Example

{
  "result": {
    "answer": "The weather in San Francisco is currently 65°F with partly cloudy skies.",
    "confidence": 0.95,
    "sources": ["current_weather_api"]
  },
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 18,
    "total_tokens": 42
  },
  "metadata": {
    "execution_time": 1.23,
    "agent_version": "1.0.0",
    "request_id": "req_abc123"
  }
}

​
Error Responses

​
400 Bad Request

Missing required field: 
{
  "error": {
    "code": "MISSING_REQUIRED_FIELD",
    "message": "Field 'query' is required",
    "status": 400
  }
}

​
404 Not Found

Agent doesn’t exist: 
{
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "Agent 'agent-123' not found",
    "status": 404
  }
}

​
429 Rate Limited

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "status": 429,
    "retry_after": 60
  }
}

​
Best Practices

  1. Include Session ID for conversations to maintain context
  2. Set Appropriate Timeouts as agent processing can take time
  3. Handle Errors Gracefully with retry logic for 5xx errors
  4. Monitor Token Usage to optimize costs

​
See Also