> ## Documentation Index > Fetch the complete documentation index at: https://docs.trymaitai.com/llms.txt > Use this file to discover all available pages before exploring further. # 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: 1. 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. ## OpenAPI ````yaml /openapi.yaml post /agents/import openapi: 3.1.0 info: title: Maitai Platform API description: > The Maitai Platform API lets you programmatically manage every resource available in the Maitai Portal, applications, intents, agents, datasets, test sets, finetune runs, and more. ## Authentication All endpoints require a valid Maitai API key passed via the `X-Maitai-Api-Key` header. You can create API keys in the [Portal](https://portal.trymaitai.com) under **Settings > API Keys**. version: 1.0.0 contact: name: Maitai Support email: support@trymaitai.com url: https://trymaitai.ai servers: - url: https://api.trymaitai.ai/api/v1 description: Production security: - ApiKeyAuth: [] tags: - name: Applications description: >- Manage applications and their configuration, intents, sessions, workflow runs, and models. - name: Analytics description: Read request volume and fault-rate analytics. - name: Intents description: Manage intents (application actions) nested under applications. - name: Intent Groups description: >- Cross-application intent grouping and access to related resources like sentinels, models, test sets, and datasets. - name: Agents description: >- Manage agents, actions, sub-agents, versions, releases, sessions, routing rules, and form fields. - name: Compositions description: Manage dataset compositions used for finetuning. - name: Sentinels description: >- Manage sentinels, evaluation watchers that monitor model output quality at the intent group level. - name: Monitors description: >- Manage reusable production monitors and their target attachments. Surface area summary (everything is scoped to the caller's company_id): * Core CRUD on monitors and their target attachments (intent / workflow / agent). * Lifecycle helpers (activate / pause monitor; enable / disable target). * Versioning + named releases (publish a snapshot, manage release pointers). * Activity time series + metrics rollups (charts, "is X healthy?" calls). * Run history (paginated `monitor_run` browsing + reverse lookup by source). * Live preview (run a monitor against an ad-hoc payload without persisting). * Discovery (find monitors attached to a given target). * Sample fetch (peek at the most recent production payload for a target). - name: Sessions description: >- View and manage classic (non-agent) chat sessions, timelines, and feedback. - name: Requests description: View and correct individual request/response pairs from chat completions. - name: Datasets description: Manage curated request sets used for model training (finetune datasets). - name: Evaluation Criteria description: Manage reusable evaluation criteria for test runs. - name: Unified Test Sets description: >- Unified Test Sets. Consumer-agnostic test-set family, the same set can drive MODEL, WORKFLOW, and AGENT runs. Sits alongside the legacy `test_sets.py` blueprint (mounted at `/test-sets`) for a graceful deprecation window; portal/SDK callers migrate here without breaking existing integrations. Sets are curated collections of `(canonical_input, canonical_expected_output)` pairs. Items can be hand-authored (MANUAL) or imported from a production `chat_completion_request`, `workflow_run`, or agent task; imports are idempotent at the DB level via partial unique indexes. When scoring a run, an optional per-item `expected_output` override (`test_set_item_response_sub`) shadows the item's baseline, that's how the portal supports "correct the answer, re-score" without mutating the imported ground truth. - name: Unified Test Runs description: >- Unified Test Runs. Execute a unified `test_set` against a MODEL / WORKFLOW / AGENT consumer and score the result. Sits alongside the legacy `test_runs.py` blueprint (mounted at `/test-runs`) for a graceful deprecation window; the legacy blueprint keeps serving the per-family run endpoints, portal/SDK callers migrate here. Lifecycle (state machine on `unified_test_run.status`): CREATED -> RUNNING -> COMPLETED * ``POST /`` -> CREATED (validates consumer_config, derives consumer_id, no items yet) * ``POST /{id}/prepare`` -> RUNNING (walks the set, adapts inputs, inserts per-item run rows) * ``POST /{id}/execute`` -> **non-blocking**. Schedules the conductor (in-proc asyncio task in dev, K8s Job in prod) and returns the run in RUNNING. Actual per-item work happens off-thread; callers poll ``/{id}/progress`` for completion. * ``GET /{id}/progress`` -> aggregate counts + duration percentiles. Portal polls this while a run is in flight. * ``POST /{id}/score`` -> unchanged status; populates matched / diff_result per item and returns a summary. Idempotent; safe to rerun after adding a response-sub override on an item. * ``POST /{id}/reset-failed`` -> COMPLETED -> RUNNING for reruns of just the FAILED items (S6). Skipped if the run has zero failures. * ``DELETE /{id}`` -> hard-delete run + items (S7). Plus a pure read path (``POST /preview-adapted-input``) that runs the input adapter for a single item against hypothetical run parameters, the portal wizard uses this to render "here's your adapted input" without paying for a real run. - name: Workflows description: >- Manage workflows, workflow versions/releases, artifacts, runs, and execution. - name: Finetune Runs description: Create, monitor, and cancel model finetuning jobs. - name: Evaluations description: >- Run batch evaluations against sentinels and view per-request scoring results. - name: Models description: View and manage available base and finetuned models. - name: Reports description: Read fault and fallback reports. - name: Tags description: Manage request tagging rules and tag runs. - name: Search description: Natural-language search over the Maitai API + CLI surface. - name: Help description: Natural-language implementation help for the Maitai platform. paths: /agents/import: post: tags: - Agents summary: Import agents description: >- 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: 1. 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. operationId: importAgents requestBody: required: true content: application/json: schema: type: object properties: application: type: object properties: id: type: integer ref_name: type: string name: type: string create_if_missing: type: boolean agents: type: array items: type: object properties: name: type: string description: type: string instructions: type: string base_url: type: string model_config_overrides: type: object actions: type: array handoffs: type: array items: type: string form_fields: type: array execution_mode: type: string enum: - route - reasoning description: >- Persisted execution mode for the agent runtime. Reasoning-style sources (OpenAI Agents SDK) should set 'reasoning'. meta: type: object required: - name source: type: string on_conflict: type: string prune: type: boolean required: - application - agents example: 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: [] responses: '200': description: Import agents. content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' example: 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: [] components: schemas: SuccessResponse: type: object properties: data: {} securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-Maitai-Api-Key description: Your Maitai API key from the Portal. ````