Invoke an agent and receive a synchronous response.
Request
POST https://api.run-agent.ai/v1/agents/{agent_id}/invokeContent-Type: application/jsonAuthorization: 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 requestsresponse = 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" }}