Skip to main content
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 · 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

​
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 → 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 · Agent Flow Steps

​
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

​
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: 
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. For performance flags like high_performance, see Execution Mode — performance options.