MCP documentation | MCP docs for agents
ark_start_agent_session
ark.start_agent_session
Create an MCP or hosted-agent session record for run tracking, budgets, approval linkage, and audit attribution.
- Availability
- Expanded preview
- Scopes
agents:write- ARK permissions
- None
- Team visibility
- Not entity-scoped
- Approval policy
draft_only- ARK approval request
- Not required
- Idempotency
- Required for external execution
- Read-only
- No
- Destructive
- No
- External side effect
- No
- Rate limit
- OAuth MCP credential and organization budgets
Input
titlestringOptional short label for the agent session.
min length: 1; max length: 160
goalstringUser-approved goal or work description for the session.
min length: 1; max length: 2000
clientNamestringAI client or hosted-agent name.
min length: 1; max length: 160
clientSessionIdstringClient-provided session identifier to link repeated calls.
min length: 1; max length: 200
maxToolCallsintegerOptional tool-call budget for the session.
min: 1; max: 10000
expiresInMinutesintegerMinutes before the session should expire.
default: 480; min: 5; max: 43200
metadataobjectNon-secret session metadata.
Result
The tool returns the canonical ark.start_agent_session operation result in structuredContent and mirrors the same JSON as text. Errors set isError: true and return a stable error code, message, and optional details.