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 The unique identifier of the agent to invoke
Request Body The input query or prompt for the agent
Additional parameters for the agent Sampling temperature (0.0 to 2.0)
Maximum tokens in response
Additional context for the agent
Session ID for maintaining conversation context
Response Token usage information Tokens used in the prompt
Tokens used in the response
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
Include Session ID for conversations to maintain contextSet Appropriate Timeouts as agent processing can take timeHandle Errors Gracefully with retry logic for 5xx errorsMonitor Token Usage to optimize costs
See Also 
