Invoke Agent

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

string

required

The unique identifier of the agent to invoke

Request Body

string

required

The input query or prompt for the agent

object

Additional parameters for the agent

Show properties

number

Sampling temperature (0.0 to 2.0)

integer

Maximum tokens in response

object

Additional context for the agent

string

Session ID for maintaining conversation context

Response

object

required

The agent’s response

object

Token usage information

Show properties

integer

Tokens used in the prompt

integer

Tokens used in the response

integer

Total tokens used

object

Additional metadata

Show properties

number

Time taken in seconds

string

Version of the agent

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?"
  }'

import requests

response = requests.post(
    "https://api.run-agent.ai/v1/agents/agent-123/invoke",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "query": "What is the weather like in San Francisco?"
    }
)

result = response.json()
print(result["result"])

const response = await fetch(
  'https://api.run-agent.ai/v1/agents/agent-123/invoke',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      query: 'What is the weather like in San Francisco?'
    })
  }
);

const result = await response.json();
console.log(result.result);

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

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

Reference

API Reference

SDK Reference

CLI Reference

Configuration

POST /v1/agents/{agent_id}/invoke

Request

Path Parameters

Request Body

Response

Examples

Basic Invocation

With Parameters

Response Example

Error Responses

400 Bad Request

404 Not Found

429 Rate Limited

Best Practices

See Also

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

​Request

​Path Parameters

​Request Body

​Response

​Examples

​Basic Invocation

​With Parameters

​Response Example

​Error Responses

​400 Bad Request

​404 Not Found

​429 Rate Limited

​Best Practices

​See Also

POST /v1/agents/{agent_id}/invoke

Request

Path Parameters

Request Body

Response

Examples

Basic Invocation

With Parameters

Response Example

Error Responses

400 Bad Request

404 Not Found

429 Rate Limited

Best Practices

See Also