> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trymaitai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build an Agent

> Create a new Agent, add capabilities, and configure how it executes

This recipe shows how to build an Agent from scratch: giving it tools (Capabilities), choosing how it executes (Execution Mode), and tuning its behavior.

## 1) Create the Agent

1. Go to **Forge > Agents**.
2. Click **Create Agent**.
3. Fill in the basics:
   * **Name**: e.g., "Support Triage Bot".
   * **Description**: What the agent does (used for routing if this agent is a sub-agent).
   * **Execution Mode**: **Reasoning** (multi-step planning loop, the default) or **Route** (each request goes straight to one capability). You can change this later from the Configuration tab, but not per-request.
   * **Application**: Where the agent's traffic is monitored.
   * **Base URL** (optional): A default API host for any API Actions this agent uses.

See: [Create Agent](/build/agents/create_agent) · [Execution Mode](/build/agents/execution_mode)

## 2) Add Capabilities

Capabilities are the "tools" your agent can use.

1. Open your new Agent.
2. Go to the **Capabilities** tab.
3. Click **Add Capability** and choose a type:
   * **LLM Action**: A sub-task handled by an LLM prompt (e.g., "Summarize Ticket").
   * **API Action**: An external API call (e.g., "Get User Profile").
   * **Webhook Creation**: Pause the session until an external system calls back.
   * **Maitai Workflow**: Run a hosted multi-step workflow.
   * **Sub-Agent**: Delegate to another existing agent.

Give each capability a clear description plus **When to use / When not to use** guidance, both routing and orchestration rely on them.

See: [Capabilities](/build/agents/capabilities/llm_action)

## 3) Configure execution

Open the **Configuration** tab. What you see depends on the agent's execution mode:

**Reasoning mode**: the Agent Flow pipeline (Orchestrate, Action, Process, Progress Probe, then Respond):

* Toggle the optional **Process** and **Progress Probe** steps.
* Click any step to customize its system prompt, model, and parameters.

**Route mode**: the routing strategy:

* **LLM Routing**: the model selects the best capability from the request, state, and capability descriptions.
* **Rules-Based Routing**: ordered deterministic rules (e.g., "If message contains 'refund', route to RefundCapability"), with a default route as fallback.

See: [Execution Mode](/build/agents/execution_mode) · [Agent Flow Steps](/build/agents/agent_flow)

## 4) Define State

If your agent needs to remember specific information across the session (like a user's name or order ID), define it as state.

1. Go to the **State** tab.
2. Add fields (e.g., `order_id`, `user_email`) with a type and a clear description.
3. Set **Read/Write Scope** to control which sub-agents can see or update each field.

See: [Agent State](/build/agents/agent_state)

## 5) Test in Studio

Verify your agent works as expected.

1. Go to **Forge > Studio**.
2. Select your Agent.
3. Chat with it to verify routing, state collection, and capability execution.

## 6) Publish

Portal edits land on the agent's draft. When the behavior looks right in Studio, click **Publish** to create an immutable version, and optionally label it with a release name like `prod` to pin production traffic to it.

## 7) Call the agent from your application

Invoke the agent from code:

* [Agent Call](/sdk/agent_call)

```python theme={null}
request = AgentRequest(
    agent="Support Triage Bot",
    application="YOUR_APPLICATION",
    session_id="session-123",
    params=ChatCompletionParams(
        messages=[{"role": "user", "content": "Handle refund for order 12345"}],
    ),
)
```

For per-request control (pinning versions, seeding state, disabling capabilities, supplying secrets) see [Agent Call](/sdk/agent_call). For performance flags like `high_performance`, see [Execution Mode, performance options](/build/agents/execution_mode#performance-options).