Invoke a specific agent
POST/v1/agent/:identifier/invoke
This route allows you to create an agent's invocation.
To learn more about AI agents, check out the documentation.
Request
Parameters (JSON)
{
"parameters": [
{
"schema": {
"type": "string"
},
"in": "query",
"name": "invocation_identifier",
"required": false,
"description": "Optional existing invocation id when continuing a multi-step interaction."
},
{
"schema": {
"type": "string"
},
"in": "query",
"name": "conversation_identifier",
"required": false,
"description": "Conversation ID for clients continuing a thread."
},
{
"schema": {
"type": "boolean"
},
"in": "query",
"name": "stream",
"required": false,
"description": "If true, response may stream (when supported) instead of a single payload."
},
{
"schema": {
"type": "boolean"
},
"in": "query",
"name": "use_mcp",
"required": false,
"description": "If true, MCP tools may be used for this invocation when configured."
},
{
"schema": {
"type": "string"
},
"in": "path",
"name": "identifier",
"required": true,
"description": "The identifier of the agent you want to operate on."
}
]
}Request body schema (JSON)
{
"title": "Body",
"body": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"prompt": {
"description": "The user's message or query to be processed by the AI agent.",
"type": "string"
},
"labels": {
"description": "Optional meta-data about the invocation.",
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"provider": {
"description": "The AI provider for this invocation. Use `openai-compatible`, `anthropic-compatible`, `vertex-gemini`, or `vertex-anthropic` with a model you registered via the [LLM management API](https://docs.port.io/api-reference/create-or-connect-an-llm-provider). See the [OpenAI compatible](https://docs.port.io/port-ai/llm-providers-management/providers/openai-compatible), [Anthropic compatible](https://docs.port.io/port-ai/llm-providers-management/providers/anthropic-compatible), [Vertex Gemini](https://docs.port.io/port-ai/llm-providers-management/providers/vertex-gemini), and [Vertex Anthropic](https://docs.port.io/port-ai/llm-providers-management/providers/vertex-anthropic) setup guides.",
"type": "string",
"enum": [
"openai",
"azure-openai",
"anthropic",
"azure-anthropic",
"bedrock",
"port",
"openai-compatible",
"vertex-gemini",
"vertex-anthropic",
"anthropic-compatible"
]
},
"model": {
"anyOf": [
{
"type": "string",
"enum": [
"gpt-5",
"gpt-5.6-luna",
"gpt-5.6-terra",
"claude-sonnet-4-20250514",
"claude-sonnet-4-5-20250929",
"claude-sonnet-4-6",
"claude-sonnet-5",
"claude-sonnet-5-5",
"claude-haiku-4-5-20251001",
"claude-opus-4-5-20251101",
"claude-opus-4-6"
]
},
{
"type": "string",
"minLength": 3,
"description": "Custom model name (for example from an OpenAI-compatible, Anthropic-compatible, Vertex Gemini, or Vertex Anthropic provider you configured)."
}
]
},
"toolApprovals": {
"description": "Tool call approvals to continue a paused invocation. Mutually exclusive with prompt.",
"type": "array",
"items": {
"type": "object",
"properties": {
"toolCallId": {
"type": "string",
"description": "The ID of the tool call to approve or reject."
},
"action": {
"type": "string",
"enum": [
"approve",
"approve_with_edit",
"reject"
],
"description": "The action to take on the tool call."
},
"editedArguments": {
"description": "Required if action is approve_with_edit. The edited arguments to use.",
"type": "object",
"additionalProperties": {}
},
"rejectionReason": {
"description": "Optional reason if rejecting the tool call. Passed to LLM.",
"type": "string"
}
},
"required": [
"toolCallId",
"action"
]
}
},
"async": {
"description": "If true, the invocation runs in the background and returns immediately with an invocation identifier.",
"type": "boolean"
},
"outputSchema": {
"description": "JSON Schema for structured output validation. When provided, the AI response will be validated against this schema.",
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"object"
],
"description": "Root JSON Schema type for structured output."
},
"properties": {
"description": "JSON object properties for structured output. Values may be nested JSON Schema fragments.",
"type": "object",
"additionalProperties": {}
},
"required": {
"description": "List of required property names for the top-level object.",
"type": "array",
"items": {
"type": "string",
"description": "A required property name."
}
}
},
"required": [
"type"
],
"additionalProperties": {}
}
}
}
}
}
}
}Responses
- 202
- 400
- 404
- 409
- 500
Default Response
Default Response
Default Response
Default Response
Default Response
Responses (JSON)
{
"responses": {
"202": {
"description": "Default Response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"invocationIdentifier": {
"type": "string",
"description": "The invocation id to use when polling for results."
},
"traceID": {
"type": "string"
}
},
"required": [
"ok",
"invocationIdentifier",
"traceID"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "Default Response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"error": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": {}
}
},
"required": [
"ok",
"error"
],
"additionalProperties": false
}
}
}
},
"404": {
"description": "Default Response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"error": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": {}
}
},
"required": [
"ok",
"error"
],
"additionalProperties": false
}
}
}
},
"409": {
"description": "Default Response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"error": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": {}
}
},
"required": [
"ok",
"error"
],
"additionalProperties": false
}
}
}
},
"500": {
"description": "Default Response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"error": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": {}
}
},
"required": [
"ok",
"error"
],
"additionalProperties": false
}
}
}
}
}
}