agent

---

title: Agent sidebar_label: Agent (12) sidebar_position: 4 doc_type: reference

Agent

Overview

Invoke AI agents, review sessions, and analyze performance.

Prerequisites

• API key with the MCP preset and required scopes
• Configured MCP client (see Configuration)

Quick start examples

Invoke an agent and track execution

1. Launch an agent task :

{
  "name": "agent_invoke",
  "arguments": {
    "agentId": "uuid-de-lagent",
    "task": "Analyse les fournisseurs actifs"
  }
}

2. Check execution status :

{
  "name": "agent_status",
  "arguments": {
    "taskId": "uuid-de-la-tache"
  }
}

3. Review conversation history :

{
  "name": "agent_get_history",
  "arguments": {
    "agentId": "uuid-de-lagent"
  }
}

---

agent_cancel

[CONTROL] Cancel a running agent invocation.

USE WHEN: • Agent is taking too long • Need to stop due to detected issues • User requested cancellation RETURNS: Success status, previous status, cancellation confirmation FEATURES: • Cancels pending or running tasks • Optional cancellation reason • Emits cancellation event for cleanup REQUIRES: taskId (from agent_invoke); optional: reason RELATED: • agent_status: Check status before cancelling • agent_invoke: Restart if needed EXAMPLE: "Stop the running agent" or "Cancel agent task X" → this tool

Scope	mcp.agent.execute
Read-only	No
Destructive	Yes
Idempotent	No

Parameters

Parameter	Type	Required	Description
taskId	string	Yes	Task ID from agent_invoke
reason	string	No	Reason for cancellation

Response

Field	Type	Description
taskId	string
cancelled	boolean
previousStatus	string
message	string

Related tools : agent_status, agent_invoke

---

agent_create_from_template

[MUTATION] Create a new agent using one of 58+ pre-configured templates.

USE WHEN: • Need to quickly create a specialized agent • Want pre-configured tools and system prompts for common use cases • Building agents for data analysis, compliance, document processing, etc. RETURNS: New agent ID, name, template used, tools enabled FEATURES: • 58+ templates: data-analyst, ontology-navigator, workflow-debugger, compliance-auditor, etc. • Discovery mode: Use templateId="list" to browse all templates • Customizable: Override system prompt, add/remove tools • Pre-configured LLM settings and safety configs REQUIRES: templateId (or "list"), name; optional: description, folderId, customizations RELATED: • agent_list: Browse created agents • agent_get: View agent configuration • agent_invoke: Execute the new agent EXAMPLE: "Create a data analyst agent" → this tool with templateId="data-analyst"

Scope	mcp.write
Read-only	No
Destructive	No
Idempotent	No

Parameters

Parameter	Type	Required	Description
customizations	object	Yes
name	string	Yes	Name for the new agent
templateId	string	Yes
description	string	No	Custom description (optional, uses template default if not provided)
folderId	string (uuid)	No	Folder ID to place agent in
removeTools	array	No	Tools to remove from template defaults
systemPrompt	string	No	Override template system prompt
tools	array	No	Additional tools to enable

Response

Field	Type	Description
success	boolean
agentId	string
agentName	string
templateUsed	string
templateCategory	string
toolsEnabled	array
message	string
availableTemplates	array

Related tools : agent_list, agent_get, agent_invoke

---

agent_get

[QUERY] Get detailed agent definition: config, system prompt, tools, knowledge sources.

USE WHEN: • Need to understand agent capabilities before invocation • Reviewing agent configuration (system prompt, model, tools) • Checking what knowledge sources an agent uses RETURNS: Complete definition with config, model, tools, knowledge sources, system prompt FEATURES: • Resolve by ID, API name, or display name • Shows tool configuration and knowledge sources • Includes versioning and template info REQUIRES: agentId OR apiName OR agentName (at least one) RELATED: • agent_invoke: Execute the agent • agent_get_history: View past conversations • agent_list: Find agent first EXAMPLE: "What can the KYC agent do?" or "Show agent configuration" → this tool

Scope	mcp.read
Read-only	Yes
Destructive	No
Idempotent	Yes

Parameters

Parameter	Type	Required	Description
agentId	string	No	Agent ID (UUID) to retrieve
agentName	string	No	Agent display name (e.g., "Compliance Analyst Assistant"), case-insensitive
apiName	string	No	Agent API name/slug (e.g., "compliance-analyst-assistant")

Related tools : agent_list, agent_invoke, agent_get_history

---

agent_get_history

[HISTORY] Get conversation history for an agent or specific session.

USE WHEN: • Need context from previous conversations • Debugging past interactions • Reviewing agent usage patterns RETURNS: Sessions with messages, timestamps, status, original queries, execution details FEATURES: • Per-session message logs • Original query tracking • Duration and status per session • Correlation ID for request tracing • Pagination support REQUIRES: agentId OR agentApiName OR sessionId (at least one); optional: includeMessages, messageLimit, limit, offset RELATED: • agent_get_tool_calls: Detailed tool execution for a session • agent_invoke: Continue conversation with conversationId EXAMPLE: "What did we discuss before?" or "Show conversation history" → this tool

Scope	mcp.read
Read-only	Yes
Destructive	No
Idempotent	Yes

Parameters

Parameter	Type	Required	Description
agentApiName	string	No	Agent API name (alternative to agentId)
agentId	string (uuid)	No	Agent ID to get history for
includeMessages	boolean	No	Include message logs for each session (default : true)
limit	number	No	Maximum sessions to return (default : 20)
messageLimit	number	No	Maximum messages per session (default : 20)
offset	number	No	Offset for pagination (default : 0)
sessionId	string (uuid)	No	Specific session/conversation ID to get history for

Response

Field	Type	Description
agentId	string
agentName	string
agentApiName	string
sessions	array
pagination	object
total	number
limit	number
offset	number
hasMore	boolean

Related tools : agent_get_tool_calls, agent_invoke

---

agent_get_performance

[ANALYTICS] Get aggregated performance metrics for an agent over time.

USE WHEN: • Evaluating agent performance over time • Identifying bottlenecks or error patterns • Optimizing agent configuration RETURNS: Latency percentiles (p50/p95/p99), success rates, token usage, tool stats, health score FEATURES: • Configurable time ranges (1h, 24h, 7d, 30d) • Per-tool breakdown with success rates • LLM usage statistics with token counts • Error pattern analysis with fingerprinting • Health score with recommendations REQUIRES: agentId; optional: timeRange, includeToolBreakdown, includeLlmBreakdown, includeErrorAnalysis RELATED: • agent_get_tool_calls: Specific session tool calls • agent_get_history: Browse session details EXAMPLE: "How is my KYC agent performing?" or "Show agent metrics" → this tool

Scope	mcp.read
Read-only	Yes
Destructive	No
Idempotent	Yes

Parameters

Parameter	Type	Required	Description
agentId	string (uuid)	Yes	Agent definition ID to analyze
includeErrorAnalysis	boolean	No	Include error pattern analysis (default : true)
includeLlmBreakdown	boolean	No	Include per-model LLM statistics (default : true)
includeToolBreakdown	boolean	No	Include per-tool statistics (default : true)
timeRange	choice (1h, 24h, 7d, 30d)	No	Time range for metrics aggregation (default : "24h")

Response

Field	Type	Description
agentId	string
timeRange	string
period	object
start	string
end	string
sessions	object
total	number
successful	number
failed	number
retryable	number
cancelled	number
successRate	number
tools	array
llm	array
errors	array
summary	object
healthScore	number
recommendations	array

Related tools : agent_get_tool_calls, agent_get_history

---

agent_get_tool_calls

[DEBUG] Get all tool calls made by an agent during execution.

USE WHEN: • Debugging agent behavior • Understanding how the agent produced its response • Analyzing tool execution patterns RETURNS: List of tool calls with inputs, outputs, status, durations, error details FEATURES: • Per-tool input/output preview • Duration tracking per call • Error details with type classification • Iteration tracking for loops • Success rate statistics REQUIRES: sessionId (conversationId from agent_invoke); optional: includeResults, includeErrors, limit RELATED: • agent_status: Get overall execution result • agent_get_history: Browse past sessions EXAMPLE: "What tools did the agent use?" or "Debug agent execution" → this tool

Scope	mcp.read
Read-only	Yes
Destructive	No
Idempotent	Yes

Parameters

Parameter	Type	Required	Description
sessionId	string (uuid)	Yes	Session ID (conversation ID) from agent_invoke
includeErrors	boolean	No	Include error details for failed tool calls (default : true)
includeResults	boolean	No	Include tool call results (output preview) (default : true)
limit	number	No	Maximum tool calls to return (default : 50)

Response

Field	Type	Description
sessionId	string
agentId	string
sessionStatus	string
toolCalls	array
stats	object
totalCalls	number
successCount	number
errorCount	number
totalDurationMs	number
successRate	number

Related tools : agent_status, agent_get_history

---

agent_invoke

[EXECUTION] Invoke an agent with a message, returns task ID for tracking.

USE WHEN: • Ready to ask the agent a question or perform a task • Starting or continuing a multi-turn conversation • Executing agent with custom context RETURNS: taskId for status tracking, conversationId for follow-up, streamUrl for SSE FEATURES: • Async execution with SSE streaming support • Multi-turn conversations via conversationId • Custom context injection • LangGraph state machine execution (Parse→Plan→Execute→Evaluate→Synthesize) REQUIRES: agentId OR apiName, message; optional: conversationId, context, streaming RELATED: • agent_status: Track execution progress and get result • agent_cancel: Stop running execution • agent_get_tool_calls: See what tools the agent used EXAMPLE: "Ask the KYC agent to check compliance" → this tool

Scope	mcp.agent.execute
Read-only	No
Destructive	No
Idempotent	No

Parameters

Parameter	Type	Required	Description
message	string	Yes	Message/prompt to send to the agent
agentId	string (uuid)	No	Agent ID to invoke
apiName	string	No	Agent API name to invoke (alternative to agentId)
context	record	No	Additional context to pass to the agent
conversationId	string (uuid)	No	Existing conversation ID for multi-turn chat
streaming	boolean	No	Enable streaming response (recommended for long tasks) (default : true)

Response

Field	Type	Description
taskId	string
conversationId	string
status	enum
streamUrl	string
message	string

Example

{
  "name": "agent_invoke",
  "arguments": {
    "agentId": "uuid-de-lagent",
    "task": "Analyse les fournisseurs actifs"
  }
}

Related tools : agent_status, agent_cancel, agent_get_tool_calls

---

agent_list

[DISCOVERY] List available agents with status, type, and configuration.

USE WHEN: • Need to discover available agents in the workspace • Finding an agent by name, type, or status RETURNS: List of agents with IDs, names, API names, status, types, versions FEATURES: • Filter by status (draft, published, archived) • Filter by agent type (conversational, task_executor, etc.) • Search by name or description • Pagination support REQUIRES: optional: status, agentType, folderId, search, limit, offset RELATED: • agent_get: Get full agent definition with config • agent_invoke: Execute an agent • agent_get_performance: View metrics EXAMPLE: "What agents exist?" or "Find the KYC agent" → this tool

Scope	mcp.read
Read-only	Yes
Destructive	No
Idempotent	Yes

Parameters

Parameter	Type	Required	Description
agentType	choice (conversational, task_executor, data_analyzer, custom)	No	Filter by agent type
folderId	string (uuid)	No	Filter by folder ID
limit	number	No	Maximum agents to return (default : 50)
offset	number	No	Offset for pagination (default : 0)
search	string	No	Search by agent name or description
status	choice (draft, published, archived)	No	Filter by agent status

Response

Field	Type	Description
agents	array
total	number
hasMore	boolean

Example

{
  "name": "agent_list",
  "arguments": {}
}

Related tools : agent_get, agent_invoke, agent_get_performance

---

agent_status

[MONITORING] Get current status and result of an agent invocation.

USE WHEN: • Tracking a running agent execution • Checking if agent completed • Retrieving the final response RETURNS: Status (pending/running/completed/failed/cancelled), response text, tool calls, timing FEATURES: • Progress percentage for long-running tasks • Tool call results included • Error details on failure • Cancellation reason if stopped REQUIRES: taskId (from agent_invoke) RELATED: • agent_get_tool_calls: Detailed tool execution trace • agent_cancel: Stop running execution • agent_invoke: Start new execution EXAMPLE: "Is the agent done?" or "Get agent response" → this tool

Scope	mcp.read
Read-only	Yes
Destructive	No
Idempotent	Yes

Parameters

Parameter	Type	Required	Description
taskId	string	Yes	Task ID from agent_invoke

Response

Field	Type	Description
taskId	string
status	enum
progress	number
result	unknown
response	string
toolCalls	array
tool	string
metadata	record
error	string
cancellationReason	string
startedAt	string
completedAt	string

Related tools : agent_invoke, agent_cancel, agent_get_tool_calls

---

agent_studio_get_definition

[READ] Get the full configuration of an agent from Agent Studio.

USE WHEN: • Need to inspect agent model, temperature, and system prompt • Checking which tools an agent has access to • Reviewing agent configuration before modification RETURNS: Full agent definition including config (model, temperature, tools, systemPrompt) LOOKUP: Can find by agentId (UUID) or agentName (case-insensitive) REQUIRES: agentId OR agentName RELATED: • agent_studio_list_definitions: Find agents to inspect • agent_studio_update_definition: Modify agent config • agent_invoke: Run the agent EXAMPLE: "Show me the config of the Customer Support agent" → this tool

Scope	mcp.read
Read-only	Yes
Destructive	No
Idempotent	Yes

Parameters

Parameter	Type	Required	Description
agentId	string (uuid)	No	Agent ID (UUID)
agentName	string	No	Agent name (alternative to agentId, case-insensitive lookup)

Related tools : agent_studio_list_definitions, agent_studio_update_definition, agent_invoke

---

agent_studio_list_definitions

[DISCOVERY] List agent definitions from the Agent Studio.

USE WHEN: • Need to discover available agents • Searching for agents by name or status • Auditing published vs draft agents RETURNS: Agent list with names, types, statuses, invocation counts FEATURES: • Filter by status (draft, published, archived) • Full-text search on name and description • Pagination support REQUIRES: none required; optional: status, search, agentType, folderId, limit, offset RELATED: • agent_studio_get_definition: Get full agent configuration • agent_studio_update_definition: Modify agent config • agent_invoke: Run an agent EXAMPLE: "What agents are available?" or "List published agents" → this tool

Scope	mcp.read
Read-only	Yes
Destructive	No
Idempotent	Yes

Parameters

Parameter	Type	Required	Description
agentType	string	No	Filter by agent type
folderId	string (uuid)	No	Filter by folder ID
limit	number	No	Maximum agents to return (default : 20)
offset	number	No	Offset for pagination (default : 0)
search	string	No	Search agents by name or description
status	choice (draft, published, archived)	No	Filter by agent status

Response

Field	Type	Description
agents	array
total	number
hasMore	boolean

Related tools : agent_studio_get_definition, agent_studio_update_definition, agent_invoke

---

agent_studio_update_definition

[WRITE] Update an agent definition in the Agent Studio.

USE WHEN: • Changing agent model, temperature, or provider • Updating the system prompt • Adding or removing tools from an agent • Publishing, archiving, or renaming an agent RETURNS: Updated agent ID, name, status, list of changed fields CONFIG: The config object supports partial updates. Only provided fields are changed. • config.modelConfig: { provider, model, temperature } • config.systemPrompt: New system prompt text • config.tools: Full replacement list of tool names REQUIRES: agentId; at least one of: name, description, config, status RELATED: • agent_studio_get_definition: Get current config before updating • agent_studio_list_definitions: Find agent IDs EXAMPLE: "Change agent model to GPT-4o and lower temperature to 0.3" → this tool

Scope	mcp.write
Read-only	No
Destructive	No
Idempotent	Yes

Parameters

Parameter	Type	Required	Description
agentId	string (uuid)	Yes	ID of the agent to update
description	string	No	New agent description
icon	string	No	Agent icon identifier
name	string	No	New agent name
status	choice (draft, published, archived)	No	Agent status

Response

Field	Type	Description
agentId	string
name	string
status	string
updatedFields	array
updatedAt	string

Related tools : agent_studio_get_definition, agent_studio_list_definitions

---

Troubleshooting

Code	Message	Solution
403	Insufficient scope	Add mcp.agent.execute to your API key.

Need help?

Contact us: Support and contact.