Prerequisites
- Create an Agent in the Portal: Create Agent
- Get the Agent name and Application name from the Portal
Execute an Agent
OpenAI SDK usage (base_url)
If you’re already using the OpenAI SDK, you can call Maitai directly by settingmodel 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/
Per-request overlays (agent.get)
Sometimes you want to tweak how an agent behaves for a single request — seed some context, turn off a flow step, or skip a sub-agent — without changing the published agent definition. Use client.agent.get(...) to resolve the agent, adjust it locally, then send it.
The published version stays the source of truth and the security ceiling: overlays are subtractive (you can disable capabilities but never enable ones the version disabled), config changes are limited to whitelisted flow-step toggles, and state is validated against the schema defined on the agent’s State tab.
Resolves the runtime view of an agent and returns a handle you can mutate.
meta.effective_execution for auditability — inspect a run in Request Overview.
Per-request secrets
When an agent capability makes an authenticated API call, you can supply the credential at request time instead of hard-coding it in the agent. Reference the secret by name in the action’s auth or headers config using a{{secrets.NAME}} placeholder (set this up in the Portal when you build the action), then pass the value in secrets on the request.
Python
Node
- Reference by name. Only
{{secrets.NAME}}placeholders inside an action’sauth/headersare resolved — secrets never appear in prompts or the LLM context. - Validated up front. If a capability the request leaves enabled references a secret you didn’t supply, the request fails fast with a
400listing the missing names. Extra secrets you pass that nothing references are ignored. - Never stored. Secret values are not written to agent/session state, and they are redacted (replaced with their
{{secrets.NAME}}reference) before any request record is persisted. - Delegated securely. Sub-agents invoked during the run can resolve the same secrets, so a credential supplied to the root agent reaches the descendant capability that needs it.
Structured final response (response_format)
By default the agent’s final answer is freeform text. You can also set a default on the agent itself: open the Respond step on the Configuration tab and choose Response Format (structured JSON schema). That default applies on every invoke. Pass an OpenAI-style response_format on params to override for a single call — either free-shape (json_object) or constrained to a schema (json_schema).
- Respond step only. The constraint applies to the agent’s final answer. Orchestration, processing, and capability calls are unaffected, and sub-agents are never constrained.
- Streaming works unchanged. The JSON answer streams as ordinary content deltas; accumulate them into a JSON string.
- The content is a string.
choices[0].message.contentcarries the JSON — parse it client-side. When a format was applied, the stored agent response also carries it undermeta.response_format. - Default is freeform. Omit
response_format(or pass{"type": "text"}) for normal prose answers.
POST /agents/{agent_id}/invoke accepts a top-level response_format object (CLI: maitai agents invoke --response-format '<json>').
Parameters
Maitai agents support two equivalent request shapes:AgentRequest(recommended): pass arequest=...wrapper toclient.agent.completions.create(...)- OpenAI SDK (base_url): pass standard chat completion fields plus agent fields via
extra_body
Agent identification (required)
The agent name. When using the OpenAI SDK base_url approach, you can alternatively set
model to the agent name and omit this field.Required when identifying an agent by name.
Alternative identifier. If
agent is provided, it is preferred over agent_id.Optional. Alternative application identifier (legacy). Can be used with
agent instead of application.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)
How the agent processes a request — the full reasoning loop or single-step routing — is part of the agent’s configuration, not the request. Set it when you build the agent and change it from the agent’s Configuration tab in the Portal. See Execution Mode.
Maximum number of orchestration iterations before the agent stops. Useful as a safety limit for agents in
reasoning mode. Defaults to 100.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.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.
Optional task identifier used to group related agent requests.
request (AgentRequest wrapper)
Wrapper request for agent execution. Provider model inputs live under
request.params and match the standard chat completion params documented at Chat.