Skip to main content
A
Docs

Agent Builder

Define autonomous agents with tools, system prompts, reasoning limits, and conversation memory.

Creating an Agent

An agent is defined by its system prompt, the tools it can access, and its runtime configuration. The system prompt establishes the agent's persona and behavioral boundaries, while tools give it the ability to take actions and retrieve information.

curl -X POST http://localhost:8005/api/v1/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Permit Processor",
    "description": "Guides citizens through permit applications",
    "system_prompt": "You are a government permit processing assistant for Abu Dhabi. Help citizens identify required permits, check eligibility, and estimate fees. Always respond in the language the citizen uses.",
    "model": "llama-3.3-70b-versatile",
    "max_steps": 10,
    "temperature": 0.3,
    "tools": ["get_permit_types", "get_permit_steps", "check_eligibility", "estimate_fees"]
  }'

Agent Configuration Fields

FieldTypeRequiredDescription
namestringYesDisplay name for the agent
descriptionstringYesWhat the agent does
system_promptstringYesInstructions that define agent behavior
modelstringNoLLM model ID. Default: llama-3.3-70b-versatile
max_stepsintegerNoMaximum reasoning steps before forced stop. Default: 10
temperaturefloatNoLLM temperature. Lower values produce more deterministic output. Default: 0.3
toolsstring[]NoList of tool names the agent can call

The Reasoning Loop

When an agent runs, it enters a loop:

  1. The LLM receives the system prompt, conversation history, and available tool definitions
  2. The LLM decides to either respond directly or call a tool
  3. If a tool is called, the runtime executes it and feeds the result back to the LLM
  4. Steps 2-3 repeat until the LLM produces a final response or max_steps is reached

This loop is the core of agentic behavior — the LLM reasons about what information it needs, gathers it via tool calls, and synthesizes a response.

Step Limits

Set max_steps thoughtfully. Too low and the agent may not complete complex tasks. Too high and you risk excessive token consumption on poorly-defined queries. For most government use cases, 5-10 steps is sufficient.

Tools

Tools are typed functions that the agent can invoke during reasoning. Each tool has a name, description, and defined parameters that the LLM uses to decide when and how to call it.

Built-in Tools

ToolDescriptionParameters
lookup_serviceLook up government service informationservice_name
get_office_hoursGet office hours for government departmentsdepartment
check_application_statusCheck status of an application by IDapplication_id
get_permit_typesList available permit typescategory
get_permit_stepsGet step-by-step permit application processpermit_type
check_eligibilityCheck citizen eligibility for a serviceservice, criteria
estimate_feesEstimate fees for a government serviceservice_type, parameters
check_requirementsCheck document requirementsdocument_type
validate_documentValidate a submitted documentdocument_id
generate_checklistGenerate a document completeness checklistapplication_type

Tool Execution

When the LLM calls a tool, the runtime:

  1. Validates the tool name exists in the agent's allowed tools
  2. Parses and validates the parameters
  3. Executes the tool function
  4. Returns the result to the LLM as a tool response message

Each tool call is recorded in the execution trace with input parameters, output, and execution time.

Conversation Memory

Agents maintain conversation memory within a session. When using the playground or the /playground/chat endpoint, each message builds on the previous context.

# First message — agent has no prior context
curl -X POST http://localhost:8005/api/v1/playground/chat \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt-001",
    "message": "I need a restaurant permit in Abu Dhabi",
    "session_id": "sess-001"
  }'

# Second message — agent remembers the restaurant permit context
curl -X POST http://localhost:8005/api/v1/playground/chat \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt-001",
    "message": "What documents do I need?",
    "session_id": "sess-001"
  }'

Memory is scoped to session_id. Different sessions for the same agent maintain independent conversation histories.

Model Selection

Agents defaults to llama-3.3-70b-versatile via Groq, which provides strong tool-calling capabilities with low latency. For Arabic-heavy workloads, configure agents with Arabic-optimized models:

{
  "name": "Arabic Inquiry Agent",
  "model": "llama-3.3-70b-versatile",
  "system_prompt": "أنت مساعد حكومي ذكي. أجب على أسئلة المواطنين باللغة العربية.",
  "temperature": 0.2
}

The temperature parameter controls response determinism. For government applications where accuracy is critical, use values between 0.0 and 0.3.

AgentsExecution Traces