Run Agent

Execute an AI agent by name with a user message.

This endpoint runs inference using a specific agent identified by its name. The agent’s custom instructions, demonstrations, and model configuration are applied to generate a personalized response.

Path Parameters:

• agent_name: URL-friendly name of the agent to execute (lowercase with underscores)

Request Body:

• message: User message or prompt to send to the agent

Optional Headers:

• X-Session-ID: Session identifier for multi-turn conversations

Returns:

• agent_id: Unique identifier of the agent that processed the request
• model: Model ID that was used for inference
• response: Generated text response from the agent
• usage: Token usage statistics containing:
  • input_tokens: Number of tokens in the input
  • output_tokens: Number of tokens in the output
  • total_tokens: Total tokens used

Raises:

• 404: If the agent name is not found or not active
• 402: If user has insufficient quota/balance
• 500: If inference execution fails

Example Request:

POST /api/v3/agents/run-agents/customer_support_bot/run
Headers: {
  "Authorization": "Bearer <api_key>",
  "X-Session-ID": "session-xyz789"
}

{
  "message": "How do I reset my password?"
}

Example Response:

{
  "agent_id": "alignment-abc123-deployed",
  "model": "nugen-flash-instruct",
  "response": "I'd be happy to help you reset your password. Here are the steps:

1. Go to the login page
2. Click on 'Forgot Password'
3. Enter your email address
4. Check your email for a reset link
5. Follow the link and create a new password

If you don't receive the email within a few minutes, please check your spam folder. Let me know if you need any further assistance!",
  "usage": {
    "input_tokens": 245,
    "output_tokens": 98,
    "total_tokens": 343
  }
}

Notes:

• The agent_name in the URL must match the normalized agent name (lowercase with underscores)
• Include X-Session-ID header to maintain conversation context across multiple requests
• The response includes token usage for monitoring purposes
• Conversations are automatically saved if enabled in user settings