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",
    },
)

​
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"
Execution preference. Common values include auto, route, direct, reasoning.
​
max_iterations
integer
Optional cap on agent iterations.
​
high_performance
boolean
default:false
Optional performance mode flag.
​
disable_chaining
boolean
Optional flag to disable chaining across agent calls.
​
session_id
string
A unique identifier you set for the session. Recommended for tracking conversation threads.
​
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: