Skip to main content
API Actions grant your agents the ability to interact with the real world by calling external services.

​
Configuration

  • Endpoint & Schema: Define the HTTP method, URL, timeout, and a JSON schema for the action’s parameters — including which are required. Use {{parameter_name}} placeholders for dynamic values in the URL path or query.
  • Importing Specs: Bootstrap quickly by uploading an OpenAPI spec — create a single action or a full set of API Actions in bulk.
  • Usage Guidance: When to use / When not to use hints that feed routing and orchestration decisions. Specific guidance here directly improves capability selection.
  • Authentication: Store API keys and headers in Maitai, or reference per-request secrets (below).
  • Response Handling: Make Real API calls or return Mock responses for testing and prototyping.

​
Invocation Mode

Every action is either Foreground or Background. What that means in practice depends on the agent’s execution mode:
ForegroundBackground
route modeEligible to be the routed capability — its output becomes the agent’s response.Never the primary route. The router may select one background action to run in parallel with the routed capability, purely to enrich state/context for later turns.
reasoning modeResults feed the loop and can be surfaced in the agent’s final response.Context-only: results are stored for other actions and sub-agents to use, but never shown directly to the user.
Example: a background get_loan_options action gathers data silently, which a “Loan Advisor” sub-agent then uses to formulate a tailored recommendation.
Webhook Creation actions are always foreground — they pause execution and need to drive the session, so they can’t run as background enrichment.

​
Per-request secrets

Instead of storing credentials in Maitai, you can reference them by name and supply the value at request time. In the action’s auth or headers config, use a {{secrets.NAME}} placeholder: 
Authorization: Bearer {{secrets.stripe_key}}
Then pass the value when calling the agent: 
agent = client.agent.get("YOUR_AGENT_NAME", version="prod")
request = agent.to_request(
    messages=[...],
    session_id="YOUR_SESSION_ID",
    secrets={"stripe_key": "sk_live_..."},
)
Secrets are validated up front (a 400 lists any missing names), resolved only inside auth/headers, never exposed to the LLM, and redacted before any request record is persisted. Sub-agents invoked during the run can resolve the same secrets. Full details: Agent Call — per-request secrets.

​
Per-request control (SDK)

Beyond secrets, the SDK can adjust how a published agent uses its API Actions for a single request — without changing the agent definition:
  • Capability mask: subtractively disable an action (or a whole sub-agent) for one request via agent.disable_action("name"). You can only disable capabilities the published version exposes — never enable disabled ones.
  • Config overlay: toggle flow steps via agent.config.system_steps.<step>.
See Agent Call — per-request overlays.