​
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