Import agents

curl --request POST \
  --url https://api.trymaitai.ai/api/v1/agents/import \
  --header 'Content-Type: application/json' \
  --header 'X-Maitai-Api-Key: <api-key>' \
  --data '
{
  "application": {
    "ref_name": "customer-support",
    "name": "Customer Support"
  },
  "source": "openai-agents-sdk",
  "on_conflict": "error",
  "agents": [
    {
      "name": "Onboarding Agent",
      "description": "Guides new users through account setup",
      "instructions": "Always verify identity before proceeding.",
      "execution_mode": "reasoning",
      "actions": [
        {
          "action_name": "lookup_order",
          "action_type": "api_call",
          "description": "Fetch order details",
          "action_config": {
            "parameters": {
              "order_id": {
                "type": "string",
                "required": true
              }
            }
          }
        }
      ],
      "handoffs": [
        "KYC Agent"
      ]
    },
    {
      "name": "KYC Agent",
      "description": "Verifies user identity",
      "actions": []
    }
  ]
}
'

{
  "data": {
    "application_id": 42,
    "agents": [
      {
        "name": "Onboarding Agent",
        "id": 101,
        "status": "created",
        "action_ids": [
          200
        ],
        "subagent_links": [
          "KYC Agent"
        ],
        "warnings": []
      },
      {
        "name": "KYC Agent",
        "id": 102,
        "status": "created",
        "action_ids": [],
        "subagent_links": [],
        "warnings": []
      }
    ],
    "warnings": []
  }
}

Agents

Import agents

Import one or more code-defined agents into Maitai from a canonical manifest. The manifest describes the agents, their capabilities (actions), and handoffs (sub-agents) in a framework-agnostic shape. The endpoint:

Resolves or creates the target application. 2. Pre-flights every manifest agent against existing rows, so on_conflict='error' fails fast without any writes when a conflict is detected. 3. Applies the writes through the agent_service functions, which autocommit per call. These services perform read-backs and cache warming on separate asyncio tasks (asyncio.gather / create_eager_task); those child tasks open their own pooled connections, so the import must NOT run inside one outer connection.async_cursor() transaction or those read-backs cannot see the uncommitted rows (they raise ResourceNotFound). The pre-flight in step 2 is what guards against partial writes for on_conflict='error'. 4. on_conflict='update' is non-destructive: only fields the adapter actually owns are overwritten (Portal-edited fields like is_default, invocation_mode, action meta survive), and agent_config is merged rather than replaced so Portal-set keys like routing_config survive. 5. By default the import is additive — actions or sub-agent links removed from the source code are NOT deleted from Maitai. Pass prune=True (CLI: --prune) for a destructive reconcile that makes the imported code the source of truth.

POST

agents

import

Import agents

curl --request POST \
  --url https://api.trymaitai.ai/api/v1/agents/import \
  --header 'Content-Type: application/json' \
  --header 'X-Maitai-Api-Key: <api-key>' \
  --data '
{
  "application": {
    "ref_name": "customer-support",
    "name": "Customer Support"
  },
  "source": "openai-agents-sdk",
  "on_conflict": "error",
  "agents": [
    {
      "name": "Onboarding Agent",
      "description": "Guides new users through account setup",
      "instructions": "Always verify identity before proceeding.",
      "execution_mode": "reasoning",
      "actions": [
        {
          "action_name": "lookup_order",
          "action_type": "api_call",
          "description": "Fetch order details",
          "action_config": {
            "parameters": {
              "order_id": {
                "type": "string",
                "required": true
              }
            }
          }
        }
      ],
      "handoffs": [
        "KYC Agent"
      ]
    },
    {
      "name": "KYC Agent",
      "description": "Verifies user identity",
      "actions": []
    }
  ]
}
'

{
  "data": {
    "application_id": 42,
    "agents": [
      {
        "name": "Onboarding Agent",
        "id": 101,
        "status": "created",
        "action_ids": [
          200
        ],
        "subagent_links": [
          "KYC Agent"
        ],
        "warnings": []
      },
      {
        "name": "KYC Agent",
        "id": 102,
        "status": "created",
        "action_ids": [],
        "subagent_links": [],
        "warnings": []
      }
    ],
    "warnings": []
  }
}

Authorizations

X-Maitai-Api-Key

string

header

required

Your Maitai API key from the Portal.

Body

application/json

application

object

required

Show child attributes

agents

object[]

required

Show child attributes

source

string

on_conflict

string

prune

boolean

Response

200 - application/json

Import agents.

data

any

Delete agent List supplied actions

⌘I