Skip to main content

Build Your First Agent

Create an AI agent that answers questions using your data, accessible via API or webhook.

What You'll Build​

By the end of this guide, you'll have an agent that:

  • Has a defined persona and behavior rules
  • Can query a database to answer questions with real data
  • Is accessible via a webhook URL for external integrations

Prerequisites​

Step 1: Create the Agent​

You can create an agent via the console UI or the API.

In the console, go to Agents > New Agent:

  • Name: support-bot
  • Type: Assistant
  • Model: Auto (recommended — picks the best model per query)
  • System Prompt: see below

Configure the Persona​

The persona defines how your agent behaves. Create a persona_config schema:

{
  "editor_schema": {
    "persona": {
      "role": "Customer Support Agent",
      "objective": "Help customers find information about their orders and answer product questions.",
      "tone": "friendly",
      "language": "en",
      "constraints": [
        "Never invent data — always query the database first",
        "If unsure, ask the customer for clarification"
      ],
      "response_style": {
        "format": "markdown",
        "max_response_length": 1000
      }
    }
  }
}

Key decisions:

  • model: "auto" lets the system pick the cheapest model that handles each query well. For a support bot, most queries are simple (routed to a small model) but complex ones get a larger model automatically.
  • constraints are enforced rules — the LLM follows them as hard boundaries, not suggestions.

Step 2: Test the Agent​

curl -N "https://llm.zihin.ai/api/v2/agents/AGENT_ID/stream" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "What are your business hours?"}'

The response streams via SSE. Without tools, the agent answers from its training data and persona instructions.

Step 3: Add a Database Tool​

This is where agents become powerful — connect real data.

  1. Create a database connection at Connections > Add Connection
  2. Enter credentials — passwords are stored encrypted in Vault (AES-256-GCM), never in plain text
  3. Create a db_config schema on your agent:
{
  "connection_id": "CONNECTION_UUID",
  "tool_definition": {
    "name": "search_orders",
    "description": "Search customer orders by status, date range, or customer ID",
    "input_schema": {
      "type": "object",
      "properties": {
        "customer_id": { "type": "string", "description": "Customer ID" },
        "status": { "type": "string", "enum": ["pending", "shipped", "delivered"] }
      }
    }
  },
  "query_template": "SELECT * FROM orders WHERE customer_id = $1 AND status = $2 LIMIT 20",
  "parameter_mapping": ["customer_id", "status"]
}

Now the agent can query your database when a customer asks "Where is my order?". It decides when to use the tool based on the conversation — you don't need to code any logic.

Step 4: Add a Webhook Trigger​

Make the agent accessible to external systems (Slack, WhatsApp, your app):

curl -X POST https://llm.zihin.ai/api/triggers \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "x-tenant-id: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "AGENT_UUID",
    "name": "Support Webhook",
    "trigger_type": "webhook",
    "trigger_config": {
      "auth": { "type": "api_key" },
      "query_extraction": { "mode": "field", "field": "message" }
    }
  }'

The response includes a webhook_url — any system can POST to it to start a conversation with your agent.

When to use sync vs async
  • Sync (default): The webhook waits for the agent to finish and returns the response. Good for APIs and chat interfaces.
  • Async: The webhook responds immediately with 202 and delivers the result via callback. Use for channels with timeouts (WhatsApp, SMS). See Webhook Triggers.

Step 5: Publish​

Publishing locks the agent configuration, creates a version snapshot, and validates all schemas:

curl -X POST https://llm.zihin.ai/api/agents/AGENT_ID/publish \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "x-tenant-id: YOUR_TENANT_ID"

If any schema has validation errors, publishing is blocked with details on what to fix.

Next Steps​

Last updated on