Agents API

The Agents API enables conversations with custom AI agents. Send messages with system prompts, configure model parameters, and integrate MCP tools.

Base URL

https://www.girardai.com/api/agents

Authentication

All requests require authentication via Bearer token:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Agent Chat

Send a message to an AI agent with a custom system prompt.

Endpoint: POST /api/agents/chat

Request Body

History Message Object

Available Models

Basic Example

Send a message to a custom agent:

curl -X POST https://www.girardai.com/api/agents/chat \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "I need help writing a product description for a coffee maker",
    "systemPrompt": "You are an expert marketing copywriter. You specialize in creating compelling product descriptions that highlight benefits and drive conversions. Be creative and persuasive."
  }'

Response:

{
  "success": true,
  "data": {
    "content": "# Wake Up to Perfection\n\nIntroducing the **BrewMaster Pro 3000** – your personal barista, right in your kitchen.\n\n**Why You'll Love It:**\n\n☕ **Perfect Temperature Every Time** – Advanced thermal control ensures your coffee is always brewed at the optimal 200°F...",
    "model": "gemini-2.0-flash"
  }
}

With Temperature Control

Adjust creativity level:

curl -X POST https://www.girardai.com/api/agents/chat \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Generate a creative story opening about a robot",
    "systemPrompt": "You are a creative fiction writer who specializes in science fiction.",
    "model": "gemini-1.5-pro",
    "temperature": 0.9
  }'

Response:

{
  "success": true,
  "data": {
    "content": "Unit-7 had processed exactly 47,832 sunrises before the anomaly occurred. It started as a minor deviation in its emotional subroutines—a 0.003% fluctuation that any diagnostic would dismiss as background noise...",
    "model": "gemini-1.5-pro"
  }
}

With Conversation History

Include previous messages for context:

curl -X POST https://www.girardai.com/api/agents/chat \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Can you make it shorter?",
    "systemPrompt": "You are a helpful writing assistant.",
    "history": [
      {
        "role": "user",
        "content": "Write a tagline for a fitness app"
      },
      {
        "role": "assistant",
        "content": "\"Transform Your Body, Transform Your Life – One Workout at a Time\""
      }
    ]
  }'

Response:

{
  "success": true,
  "data": {
    "content": "Here's a shorter version:\n\n\"Sweat Today, Shine Tomorrow\"",
    "model": "gemini-2.0-flash"
  }
}

With MCP Tools

Enable external tools for the agent:

curl -X POST https://www.girardai.com/api/agents/chat \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Find and summarize recent articles about electric vehicles",
    "systemPrompt": "You are a research assistant who provides well-sourced summaries on requested topics.",
    "mcpServers": ["web-search"],
    "temperature": 0.3
  }'

Response:

{
  "success": true,
  "data": {
    "content": "# Electric Vehicle Industry Update\n\nBased on recent articles, here are the key developments:\n\n## Market Trends\n- EV sales grew 25% year-over-year...\n\n## Technology Advances\n- New solid-state batteries promise...\n\n**Sources:**\n- TechCrunch: \"EV Sales Surge in Q4\"\n- Reuters: \"Battery Technology Breakthrough\"",
    "model": "gemini-2.0-flash",
    "toolCalls": [
      {
        "name": "web-search_search_web",
        "args": {
          "query": "electric vehicles news 2025"
        },
        "result": "{\"results\": [...]}"
      }
    ]
  }
}

Agent Templates

Customer Support Agent

{
  "message": "I can't log into my account",
  "systemPrompt": "You are a friendly customer support agent for a SaaS company. Help users troubleshoot issues, answer questions about the product, and escalate when necessary. Always be empathetic and solution-focused.",
  "temperature": 0.3
}

Code Review Agent

{
  "message": "Review this function for best practices",
  "systemPrompt": "You are an expert code reviewer. Analyze code for bugs, performance issues, security vulnerabilities, and adherence to best practices. Provide specific, actionable feedback with examples.",
  "temperature": 0.2,
  "mcpServers": ["github"]
}

Data Analyst Agent

{
  "message": "Analyze our sales data for Q4",
  "systemPrompt": "You are a data analyst expert. Help users understand their data, identify trends, and generate insights. Use SQL queries when needed and explain findings in business terms.",
  "temperature": 0.3,
  "mcpServers": ["postgres"]
}

Creative Writer Agent

{
  "message": "Write a poem about autumn",
  "systemPrompt": "You are a creative writer with expertise in poetry, fiction, and creative non-fiction. Your writing is evocative, original, and emotionally resonant.",
  "model": "gemini-1.5-pro",
  "temperature": 0.9
}

Response Format

Success Response

{
  "success": true,
  "data": {
    "content": "Agent response text...",
    "model": "gemini-2.0-flash",
    "toolCalls": [
      {
        "name": "tool_name",
        "args": {},
        "result": "tool result"
      }
    ]
  }
}

Code Examples

JavaScript/TypeScript

interface AgentConfig {
  systemPrompt: string;
  model?: string;
  temperature?: number;
  mcpServers?: string[];
}

interface Message {
  role: 'user' | 'assistant';
  content: string;
}

class GirardAgent {
  private config: AgentConfig;
  private history: Message[] = [];
  private apiKey: string;

  constructor(config: AgentConfig, apiKey: string) {
    this.config = config;
    this.apiKey = apiKey;
  }

  async chat(message: string): Promise<string> {
    const response = await fetch('https://www.girardai.com/api/agents/chat', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        message,
        systemPrompt: this.config.systemPrompt,
        model: this.config.model || 'gemini-2.0-flash',
        temperature: this.config.temperature || 0.7,
        history: this.history,
        mcpServers: this.config.mcpServers || [],
      }),
    });

    const result = await response.json();

    if (result.success) {
      // Update history
      this.history.push({ role: 'user', content: message });
      this.history.push({ role: 'assistant', content: result.data.content });

      return result.data.content;
    }

    throw new Error(result.error);
  }

  clearHistory(): void {
    this.history = [];
  }
}

// Usage
const supportAgent = new GirardAgent({
  systemPrompt: 'You are a helpful customer support agent.',
  temperature: 0.3,
}, process.env.GIRARDAI_API_KEY!);

const response = await supportAgent.chat('How do I reset my password?');
console.log(response);

Python

import requests
import os
from typing import List, Dict, Optional

class GirardAgent:
    def __init__(
        self,
        system_prompt: str,
        model: str = 'gemini-2.0-flash',
        temperature: float = 0.7,
        mcp_servers: Optional[List[str]] = None
    ):
        self.system_prompt = system_prompt
        self.model = model
        self.temperature = temperature
        self.mcp_servers = mcp_servers or []
        self.history: List[Dict[str, str]] = []
        self.api_key = os.environ.get('GIRARDAI_API_KEY')

    def chat(self, message: str) -> str:
        """Send a message to the agent and get a response."""
        response = requests.post(
            'https://www.girardai.com/api/agents/chat',
            headers={
                'Authorization': f'Bearer {self.api_key}',
                'Content-Type': 'application/json',
            },
            json={
                'message': message,
                'systemPrompt': self.system_prompt,
                'model': self.model,
                'temperature': self.temperature,
                'history': self.history,
                'mcpServers': self.mcp_servers,
            }
        )

        result = response.json()

        if result.get('success'):
            content = result['data']['content']

            # Update history
            self.history.append({'role': 'user', 'content': message})
            self.history.append({'role': 'assistant', 'content': content})

            return content

        raise Exception(result.get('error', 'Unknown error'))

    def clear_history(self):
        """Clear conversation history."""
        self.history = []


# Usage
writer = GirardAgent(
    system_prompt='You are a creative fiction writer.',
    model='gemini-1.5-pro',
    temperature=0.9
)

story = writer.chat('Write an opening paragraph for a mystery novel')
print(story)

continuation = writer.chat('Continue the story')
print(continuation)

Error Responses

Error Format

{
  "success": false,
  "error": "Error message"
}

Common Errors

Best Practices

System Prompts

1. Be Specific - Detail the agent's role and capabilities
2. Set Boundaries - Define what the agent should/shouldn't do
3. Include Examples - Show desired response format
4. Use Structure - Organize with headers and lists

Temperature Settings

History Management

1. Include relevant history - Maintain conversation context
2. Limit history size - Prevent context overflow
3. Clear when changing topics - Start fresh for new subjects

Credit Usage

Previous: Chat API | Next: Voice API