> ## 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. # Create agent action > Add a new action (LLM, API, or webhook capability) to an agent. ## OpenAPI ````yaml /openapi.yaml post /agents/{agent_id}/actions 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/{agent_id}/actions: post: tags: - Agents summary: Create agent action description: Add a new action (LLM, API, or webhook capability) to an agent. operationId: createAgentAction parameters: - name: agent_id in: path required: true schema: type: integer requestBody: required: true content: application/json: schema: type: object properties: action_name: type: string action_type: type: string description: llm | api | webhook | maitai_workflow | integration description: type: string action_config: type: object x-cli-option: true description: >- Shape depends on action_type. LLM: {prompt, user_prompt, model_config:{model,temperature,max_tokens}}. API/webhook: {base_url,endpoint,method,headers,auth}. properties: prompt: type: string user_prompt: type: string model_config: type: object base_url: type: string endpoint: type: string method: type: string headers: type: object auth: type: object is_default: type: boolean x-cli-option: true action_result_type: type: string x-cli-option: true invocation_mode: type: string x-cli-option: true meta: type: object x-cli-option: true required: - action_name - action_type - description example: action_name: Lookup Order action_type: api description: Fetch order details from the orders API invocation_mode: foreground action_config: base_url: https://api.example.com endpoint: /orders/{order_id} method: GET headers: Accept: application/json auth: type: bearer token: '{{secrets.ORDERS_API_TOKEN}}' responses: '201': description: Create agent action. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/AgentAction' example: data: id: 200 action_name: Lookup Order action_type: api agent_id: 101 enabled: true components: schemas: AgentAction: type: object description: >- A capability that an agent can invoke, an LLM call, API call, or webhook. properties: id: type: integer readOnly: true description: Unique identifier. date_created: type: string format: date-time readOnly: true description: UTC timestamp when the action was created. agent_id: type: integer description: Parent agent ID. action_name: type: string description: Display name. Unique per agent. action_type: type: string description: >- The kind of action: `llm`: language model call, `api`: external API call, `webhook`: webhook invocation, `maitai_workflow`: Maitai workflow. enum: - llm - api - webhook - maitai_workflow description: type: string description: What this action does. enabled: type: boolean description: Whether the action is currently active. action_config: type: object nullable: true description: >- Action-specific configuration (API endpoint, headers, LLM parameters, etc.). meta: type: object description: Arbitrary metadata. is_default: type: boolean description: Whether this is the default foreground action. Only one per agent. action_result_type: type: string description: >- How the result is used: `gather_info`: use output as context for further reasoning, `complete_task`: only care about success/failure. enum: - gather_info - complete_task status: type: string description: 'Lifecycle status: `ENABLED` or `DISABLED`.' enum: - ENABLED - DISABLED invocation_mode: type: string description: 'Execution mode: `foreground`: blocking, `background`: async.' enum: - foreground - background securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-Maitai-Api-Key description: Your Maitai API key from the Portal. ````