Skip to main content
Use this when you’ve built an Agent in the Portal and want to invoke it from your application code.

​
Prerequisites

  • Create an Agent in the Portal: Create Agent
  • Get the Agent name and Application name from the Portal

​
Execute an Agent

import maitai
from maitai.models.agent.extended import AgentRequest
from maitai.models.chat import ChatCompletionParams

client = maitai.MaitaiAsync()

request = AgentRequest(
    agent="YOUR_AGENT_NAME",
    application="YOUR_APPLICATION",
    session_id="YOUR_SESSION_ID",
    params=ChatCompletionParams(
        messages=[
            {"role": "user", "content": "Help me triage this customer ticket and draft a reply."},
        ],
    ),
)

response = await client.agent.completions.create(request=request)
print(response.choices[0].message.content)

​
OpenAI SDK usage (base_url)

If you’re already using the OpenAI SDK, you can call Maitai directly by setting model to your agent name and passing application via extra_body. To use the Agents API, set the OpenAI SDK base URL to:
  • https://api.trymaitai.ai/agent/
import os
import openai

client = openai.OpenAI(
    base_url="https://api.trymaitai.ai/agent/",
    api_key=os.getenv("MAITAI_API_KEY"),
)

response = client.chat.completions.create(
    model="YOUR_AGENT_NAME",
    messages=[
        {"role": "user", "content": "Help me handle a refund for order 12345."},
    ],
    extra_body={
        "application": "YOUR_APPLICATION",
        "session_id": "YOUR_SESSION_ID",
        "execution_mode": "reasoning",   # Optional: "auto" (default), "reasoning", or "route"
        "high_performance": True,         # Optional: flatten sub-agents, run in-process
    },
)

​
Parameters

Maitai agents support two equivalent request shapes:
  • AgentRequest (recommended): pass a request=... wrapper to client.agent.completions.create(...)
  • OpenAI SDK (base_url): pass standard chat completion fields plus agent fields via extra_body

​
Agent identification (required)

​
agent
string
The agent name. When using the OpenAI SDK base_url approach, you can alternatively set model to the agent name and omit this field.
​
application
string
Required when identifying an agent by name.
​
agent_id
integer
Alternative identifier. If agent is provided, it is preferred over agent_id.
​
application_id
integer
Optional. Alternative application identifier (legacy). Can be used with agent instead of application.
​
model
string
When using the OpenAI SDK base_url approach without providing agent or agent_id, Maitai will use model as the agent name.

​
Agent execution controls (optional)

​
execution_mode
string
default:"auto"
Controls how the agent processes the request.
ValueBehavior
auto(default) Automatically selects the best mode based on the agent’s configuration. Picks reasoning if sub-agents exist or multiple actions are available; otherwise falls back to route.
reasoningActivates the full reasoning loop (Cortex). The agent plans actions via an LLM orchestrator, executes them, processes results, and iterates until it can respond. Best for complex, multi-step tasks.
routeSingle-step routing. The agent picks one capability and returns the result. Best for simple request/response patterns.
See Orchestration for more details on execution modes.
​
max_iterations
integer
Maximum number of orchestration iterations before the agent stops. Useful as a safety limit for reasoning mode. Defaults to 100.
​
high_performance
boolean
default:false
When true, the agent flattens sub-agent actions into the root agent and runs everything in-process. Instead of dispatching work to sub-agents over Redis queues, all capabilities (including those defined on sub-agents) execute directly within the root agent’s process.This eliminates inter-process overhead and reduces latency, especially for agents with deep sub-agent hierarchies. The orchestrator sees a single flat list of all available capabilities.
​
disable_chaining
boolean
default:false
Controls whether the orchestrator can plan multi-step action chains in a single LLM call.
  • false (default): Chaining ON. The orchestrator can output a sequence of actions where later actions trigger on the completion of earlier ones (e.g., “fetch data, then when that completes, enrich it”). Reduces orchestration round-trips.
  • true: Chaining OFF. The orchestrator plans one action at a time, then re-orchestrates after each completion. Simpler and more predictable.
​
disable_strategy
boolean
default:false
When true, skips the strategy-building step and goes straight to action planning. Useful when the agent’s task is straightforward and doesn’t benefit from upfront planning.
​
session_id
string
A unique identifier you set for the session. Recommended for tracking conversation threads. The agent uses this to maintain state (forms, context, checkpoints) across multiple requests.
​
task_id
string
Optional task identifier used to group related agent requests.

​
request (AgentRequest wrapper)

​
request
AgentRequest
required
Wrapper request for agent execution. Provider model inputs live under request.params and match the standard chat completion params documented at Chat.

​
Observability

To debug a single agent run in the Portal, open the resulting request in Request Overview: