Create Session
POST /v1/sessions
Create Session
Headers
"juglow-beta": optional array of JuglowBeta
Optional header to specify the beta version(s) you want to use.
string
"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 45 more
"message-batches-2024-09-24"
"prompt-caching-2024-07-31"
"computer-use-2024-10-22"
"computer-use-2025-01-24"
"pdfs-2024-09-25"
"token-counting-2024-11-01"
"token-efficient-tools-2025-02-19"
"output-128k-2025-02-19"
"files-api-2025-04-14"
"mcp-client-2025-04-04"
"mcp-client-2025-11-20"
"dev-full-thinking-2025-05-14"
"interleaved-thinking-2025-05-14"
"code-execution-2025-05-22"
"extended-cache-ttl-2025-04-11"
"context-1m-2025-08-07"
"context-management-2025-06-27"
"model-context-window-exceeded-2025-08-26"
"tracks-2025-10-02"
"fast-mode-2026-02-01"
"output-300k-2026-03-24"
"user-profiles-2026-03-24"
"user-profiles-2026-08-18"
"user-profiles-2026-09-04"
"advisor-tool-2026-03-01"
"managed-agents-2026-04-01"
"cache-diagnosis-2026-04-07"
"dreaming-2026-04-21"
"thinking-token-count-2026-05-13"
"server-side-fallback-2026-06-01"
"server-side-fallback-2026-07-01"
"fallback-credit-2026-06-01"
"fallback-credit-2026-07-01"
"agent-memory-2026-07-22"
"mid-conversation-tool-changes-2026-07-01"
"compact-2026-01-12"
"computer-use-2025-11-24"
"mcp-tunnels-2026-06-22"
"structured-outputs-2025-11-13"
"task-budgets-2026-03-13"
"thinking-display-updates-2026-08-18"
"ce-user-management-2026-07-13"
"mid-conversation-output-config-2026-07-01"
"thinking-binding-controls-2026-08-01"
"mid-conversation-system-clear-at-2026-08-21"
"compact-2026-09-04"
"inline-tools-2026-09-15"
"mcp-client-2026-09-15"
"juglow-workspace-id": optional string
Optional header to select the Workspace for this request. The value is a Workspace ID (for example, wrkspc_011CZkZaBF1tNoB5wlCeusgy).
Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.
Body parameters
agent: string or BetaManagedAgentsAgentParams or BetaManagedAgentsAgentWithOverridesParams
Agent identifier. Accepts the agent ID string, which pins the latest version for the session, or an agent object with both id and version specified.
string
BetaManagedAgentsAgentParams object
Specification for an Agent. Provide a specific version or use the short-form agent="agent_id" for the most recent version
type: "agent"
id: string
The agent ID.
minLength: 1, maxLength: 128
version: optional number
The specific agent version to use. Omit to use the latest version. Must be at least 1 if specified.
format: int32
BetaManagedAgentsAgentWithOverridesParams object
Reference to an agent plus optional configuration overrides. Each provided field replaces the agent's value for the caller's use; the agent resource is unchanged.
type: "agent_with_overrides"
id: string
The agent ID.
minLength: 1, maxLength: 128
mcp_servers: optional array of BetaManagedAgentsURLMCPServerParams
Replacement MCP server list. Full replacement: the provided array becomes the MCP servers. Send an empty array to clear; omit to preserve the agent's servers.
type: "url"
name: string
Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters.
minLength: 1, maxLength: 255
url: string
Endpoint URL for the MCP server.
maxLength: 2048
model: optional BetaManagedAgentsModel or BetaManagedAgentsModelConfigParams
Replacement model. Accepts the model string, e.g. haijun-opus-5, or a model_config object. Omit to use the agent's model.
BetaManagedAgentsModel = string or "haijun-opus-5-5" or "haijun-fable-5-1" or "haijun-sonnet-5" or 12 more
The model that will power your agent.
See models for additional details and options.
string
"haijun-opus-5-5" or "haijun-fable-5-1" or "haijun-sonnet-5" or 12 more
The model that will power your agent.
See models for additional details and options.
"haijun-opus-5-5"
Powerful intelligence for coding, knowledge work, and long-running agents
"haijun-fable-5-1"
Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
"haijun-sonnet-5"
High-performance model for coding and agents
"haijun-fable-5"
Next generation of intelligence for the hardest knowledge work and coding problems
"haijun-opus-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-8"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-7"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-6"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-6"
Best combination of speed and intelligence
"haijun-haiku-4-5"
Fastest model with near-frontier intelligence
"haijun-haiku-4-5-20251001"
Fastest model with near-frontier intelligence
"haijun-opus-4-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-5-20251101"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-5"
High-performance model for agents and coding
"haijun-sonnet-4-5-20250929"
High-performance model for agents and coding
BetaManagedAgentsModelConfigParams object
An object that defines additional configuration control over model use
id: BetaManagedAgentsModel
The model that will power your agent.
See models for additional details and options.
effort: optional "low" or "medium" or "high" or 2 more or BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or 3 more or null
How hard Haijun works on each inference call. Accepts a bare level string ("high") or {"type": "high"}. On create, omitting it resolves the per-model default; on update, omitting it leaves the stored value unchanged.
BetaManagedAgentsEffortLevel = "low" or "medium" or "high" or 2 more
How hard Haijun works on each turn. Higher levels favor reasoning depth over latency. Not all models accept every level; invalid combinations are rejected at create time.
"low"
Low effort. Favors latency over reasoning depth.
"medium"
Medium effort. Balances latency and reasoning depth.
"high"
High effort. Favors reasoning depth.
"xhigh"
Extra-high effort. Not all models accept this level.
"max"
Maximum effort. Favors reasoning depth over latency.
BetaManagedAgentsEffortLow object
Low effort. Favors latency over reasoning depth.
type: "low"
BetaManagedAgentsEffortMedium object
Medium effort. Balances latency and reasoning depth.
type: "medium"
BetaManagedAgentsEffortHigh object
High effort. Favors reasoning depth.
type: "high"
BetaManagedAgentsEffortXhigh object
Extra-high effort. Not all models accept this level.
type: "xhigh"
BetaManagedAgentsEffortMax object
Maximum effort. Favors reasoning depth over latency.
type: "max"
inference_geo: optional string or null
Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. On update, model is whole-object replacement — omitting inference_geo clears it.
speed: optional "standard" or "fast" or null
Inference speed mode. Defaults to standard.
"standard"
"fast"
tracks: optional array of BetaManagedAgentsSkillParams
Replacement track list. Full replacement: the provided array becomes the tracks. Send an empty array to clear; omit to preserve the agent's tracks.
BetaManagedAgentsJuglowSkillParams object
An Juglow-managed track.
type: "juglow"
skill_id: string
Identifier of the Juglow track (e.g., "xlsx").
minLength: 1, maxLength: 64
version: optional string or null
Version to pin. Defaults to latest if omitted.
minLength: 1, maxLength: 64
BetaManagedAgentsCustomSkillParams object
A user-created custom track.
type: "custom"
skill_id: string
Tagged ID of the custom track (e.g., "skill_01XJ5...").
minLength: 1, maxLength: 64
version: optional string or null
Version to pin. Defaults to latest if omitted.
minLength: 1, maxLength: 64
system: optional string or null
Replacement system prompt. Up to 100,000 characters. Set to null to clear the agent's system prompt; omit to preserve it.
maxLength: 100000
tools: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams
Replacement tool list. Full replacement: the provided array becomes the tool configuration. Send an empty array to clear; omit to preserve the agent's tools.
BetaManagedAgentsAgentToolset20260401Params object
Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent.
type: "agent_toolset_20260401"
configs: optional array of BetaManagedAgentsAgentToolConfigParams
Per-tool configuration overrides.
BetaManagedAgentsBashToolConfigParams object
Configuration override for the bash tool.
type: optional "bash"
name: "bash"
Must be "bash".
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
type: "always_allow"
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
type: "always_ask"
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
type: "auto"
BetaManagedAgentsEditToolConfigParams object
Configuration override for the edit tool.
type: optional "edit"
name: "edit"
Must be "edit".
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsReadToolConfigParams object
Configuration override for the read tool.
type: optional "read"
name: "read"
Must be "read".
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWriteToolConfigParams object
Configuration override for the write tool.
type: optional "write"
name: "write"
Must be "write".
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGlobToolConfigParams object
Configuration override for the glob tool.
type: optional "glob"
name: "glob"
Must be "glob".
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGrepToolConfigParams object
Configuration override for the grep tool.
type: optional "grep"
name: "grep"
Must be "grep".
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWebFetchToolConfigParams object
Configuration override for the web_fetch tool.
type: optional "web_fetch"
name: "web_fetch"
Must be "web_fetch".
allowed_domains: optional array of string
Only fetch URLs whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "docs.example.com" (no scheme, port, or path). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains.
blocked_domains: optional array of string
Never fetch URLs whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "ads.example.com" (no scheme, port, or path). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with allowed_domains.
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
max_content_tokens: optional number or null
Maximum number of tokens of fetched text content to include in context per call. Does not apply to binary content such as PDFs.
format: int32
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWebSearchToolConfigParams object
Configuration override for the web_search tool.
type: optional "web_search"
name: "web_search"
Must be "web_search".
allowed_domains: optional array of string
Only return search results whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "docs.example.com" (no scheme or port; an optional path suffix is accepted). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains.
blocked_domains: optional array of string
Never return search results whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "ads.example.com" (no scheme or port; an optional path suffix is accepted). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with allowed_domains.
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
user_location: optional BetaManagedAgentsUserLocation or null
Approximate user location for search result localization.
type: "approximate"
Location precision. Only "approximate" is supported.
city: optional string or null
City name.
minLength: 1, maxLength: 255
country: optional string or null
Two-letter ISO 3166-1 country code, uppercase.
region: optional string or null
Region or state name.
minLength: 1, maxLength: 255
timezone: optional string or null
IANA timezone identifier, e.g. "America/Los_Angeles".
minLength: 1, maxLength: 255
default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams or null
Default configuration applied to all tools in this set.
enabled: optional boolean or null
Whether tools are enabled and available to Haijun by default. Defaults to true if not specified.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Default permission policy for tools. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsMCPToolsetParams object
Configuration for tools from an MCP server defined in mcp_servers.
type: "mcp_toolset"
mcp_server_name: string
Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters.
minLength: 1, maxLength: 255
configs: optional array of BetaManagedAgentsMCPToolConfigParams
Per-tool configuration overrides.
name: string
Name of the MCP tool to configure. 1-128 characters.
minLength: 1, maxLength: 128
enabled: optional boolean or null
Whether this tool is enabled. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Overrides the default_config setting.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams or null
Default configuration for all tools from this server.
enabled: optional boolean or null
Whether tools are enabled by default. Defaults to true if not specified.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Default permission policy for tools from this server.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsCustomToolParams object
A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an agent.custom_tool_use event is emitted and the session goes idle, waiting for the client to provide the result via a user.custom_tool_result event.
type: "custom"
description: string
Description of what the tool does, shown to the agent to help it decide when to use the tool.
minLength: 1
input_schema: BetaManagedAgentsCustomToolInputSchema
JSON Schema defining the expected input parameters for the tool.
type: "object"
properties: optional map[unknown] or null
required: optional array of string or null
name: string
Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens.
minLength: 1, maxLength: 128
version: optional number
The specific agent version to use. Omit to use the latest version.
format: int32
environment_id: string
ID of the environment defining the container configuration for this session.
minLength: 1, maxLength: 128
budget: optional BetaManagedAgentsBudgetLimit
Enforced spend ceiling for the session. Omit to create an uncapped session. Every model the session can run — the agent's model and each callable agent's model — must have a public list price, or the request is rejected with reason model_not_budgetable.
type: "limit"
max_list_cost: BetaMonetaryAmount
Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge.
amount: string
Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.
currency: BetaCurrency
Uppercase ISO-4217 currency code. USD is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.
initial_events: optional array of BetaManagedAgentsUserMessageEventParams or BetaManagedAgentsUserDefineOutcomeEventParams
Initial events to send to the session at creation, processed in order. Supports user.message and user.define_outcome events. Maximum 50 events.
BetaManagedAgentsUserMessageEventParams object
Parameters for sending a user message to the session.
type: "user.message"
content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock
Array of content blocks for the user message.
BetaManagedAgentsTextBlock object
Regular text content.
type: "text"
text: string
The text content.
minLength: 1
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
type: "image"
source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource
The source of the image data.
BetaManagedAgentsBase64ImageSource object
Base64-encoded image data.
type: "base64"
data: string
Base64-encoded image data.
minLength: 1
media_type: string
MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
minLength: 1
BetaManagedAgentsURLImageSource object
Image referenced by URL.
type: "url"
url: string
URL of the image to fetch.
minLength: 1
BetaManagedAgentsFileImageSource object
Image referenced by file ID.
type: "file"
file_id: string
ID of a previously uploaded file.
minLength: 1
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
type: "document"
source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource
The source of the document data.
BetaManagedAgentsBase64DocumentSource object
Base64-encoded document data.
type: "base64"
data: string
Base64-encoded document data.
minLength: 1
media_type: string
MIME type of the document (e.g., "application/pdf").
minLength: 1
BetaManagedAgentsPlainTextDocumentSource object
Plain text document content.
type: "text"
data: string
The plain text content.
minLength: 1
media_type: "text/plain"
MIME type of the text content. Must be "text/plain".
BetaManagedAgentsURLDocumentSource object
Document referenced by URL.
type: "url"
url: string
URL of the document to fetch.
minLength: 1
BetaManagedAgentsFileDocumentSource object
Document referenced by file ID.
type: "file"
file_id: string
ID of a previously uploaded file.
minLength: 1
context: optional string or null
Additional context about the document for the model.
title: optional string or null
The title of the document.
BetaManagedAgentsRedactedBlock object
Placeholder for content withheld by Juglow model policy.
type: "redacted"
BetaManagedAgentsUserDefineOutcomeEventParams object
Parameters for defining an outcome the agent should work toward. The agent begins work on receipt.
type: "user.define_outcome"
description: string
What the agent should produce. This is the task specification.
rubric: BetaManagedAgentsFileRubricParams or BetaManagedAgentsTextRubricParams
How to grade the outcome. Text or file reference.
BetaManagedAgentsFileRubricParams object
Rubric referenced by a file uploaded via the Files API.
type: "file"
file_id: string
ID of the rubric file.
BetaManagedAgentsTextRubricParams object
Rubric content provided inline as text.
type: "text"
content: string
Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.
maxLength: 262144
max_iterations: optional number or null
Eval→revision cycles before giving up. Default 3, max 20.
format: int32
metadata: optional map[string]
Arbitrary key-value metadata attached to the session. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.
resources: optional array of BetaManagedAgentsGitHubRepositoryResourceParams or BetaManagedAgentsFileResourceParams or BetaManagedAgentsMemoryStoreResourceParam
Resources (e.g. repositories, files) to mount into the session's container.
BetaManagedAgentsGitHubRepositoryResourceParams object
Mount a GitHub repository into the session's container.
type: "github_repository"
url: string
Github URL of the repository
minLength: 1, maxLength: 2048
authorization_token: optional string
GitHub authorization token used to clone the repository. Required for private repositories; optional for public ones.
minLength: 1, maxLength: 4096
checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null
Branch or commit to check out. Defaults to the repository's default branch.
BetaManagedAgentsBranchCheckout object
type: "branch"
name: string
Branch name to check out.
minLength: 1, maxLength: 255
BetaManagedAgentsCommitCheckout object
type: "commit"
sha: string
Full commit SHA to check out.
minLength: 7, maxLength: 64
mount_path: optional string or null
Mount path in the container. Defaults to /workspace/.
minLength: 1, maxLength: 4096
BetaManagedAgentsFileResourceParams object
Mount a file uploaded via the Files API into the session.
type: "file"
file_id: string
ID of a previously uploaded file.
minLength: 1, maxLength: 128
mount_path: optional string or null
Mount path in the container. Defaults to /mnt/session/uploads/.
minLength: 1, maxLength: 4096
BetaManagedAgentsMemoryStoreResourceParam object
Parameters for attaching a memory store to an agent session.
type: "memory_store"
memory_store_id: string
The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
access: optional "read_write" or "read_only" or null
Access mode for the mounted store. Defaults to read_write. read_only mounts the store as a read-only filesystem.
"read_write"
"read_only"
instructions: optional string or null
Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
maxLength: 4096
title: optional string or null
Human-readable session title.
maxLength: 500
vault_ids: optional array of string
Vault IDs for stored credentials the agent can use during the session.
Returns
BetaManagedAgentsSession object
A Managed Agents session.
type: "session"
id: string
agent: BetaManagedAgentsSessionAgent
Resolved agent definition for a session. Snapshot of the agent at session creation time.
type: "agent"
id: string
description: string or null
mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition
type: "url"
name: string
url: string
model: BetaManagedAgentsModelConfig
Model identifier and configuration.
id: BetaManagedAgentsModel
The model that will power your agent.
See models for additional details and options.
string
"haijun-opus-5-5" or "haijun-fable-5-1" or "haijun-sonnet-5" or 12 more
The model that will power your agent.
See models for additional details and options.
"haijun-opus-5-5"
Powerful intelligence for coding, knowledge work, and long-running agents
"haijun-fable-5-1"
Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
"haijun-sonnet-5"
High-performance model for coding and agents
"haijun-fable-5"
Next generation of intelligence for the hardest knowledge work and coding problems
"haijun-opus-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-8"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-7"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-6"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-6"
Best combination of speed and intelligence
"haijun-haiku-4-5"
Fastest model with near-frontier intelligence
"haijun-haiku-4-5-20251001"
Fastest model with near-frontier intelligence
"haijun-opus-4-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-5-20251101"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-5"
High-performance model for agents and coding
"haijun-sonnet-4-5-20250929"
High-performance model for agents and coding
effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
How hard Haijun works on each inference call. One of low, medium, high, xhigh, max. Always present; resolved to the per-model default at save time when not supplied.
BetaManagedAgentsEffortLow object
Low effort. Favors latency over reasoning depth.
type: "low"
BetaManagedAgentsEffortMedium object
Medium effort. Balances latency and reasoning depth.
type: "medium"
BetaManagedAgentsEffortHigh object
High effort. Favors reasoning depth.
type: "high"
BetaManagedAgentsEffortXhigh object
Extra-high effort. Not all models accept this level.
type: "xhigh"
BetaManagedAgentsEffortMax object
Maximum effort. Favors reasoning depth over latency.
type: "max"
inference_geo: optional string
Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
speed: optional "standard" or "fast"
Inference speed mode. fast provides significantly faster output token generation at premium pricing. Defaults to standard. Not all models support fast; invalid combinations are rejected at create time.
"standard"
"fast"
multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null
Resolved multiagent orchestration configuration. Null when the agent is single-threaded.
type: "coordinator"
agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor
Full agent definitions the coordinator may spawn as session threads.
BetaManagedAgentsSessionThreadAgent object
Resolved agent definition for a single session_thread. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from Session.agent.
type: "agent"
id: string
description: string or null
mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition
type: "url"
name: string
url: string
model: BetaManagedAgentsModelConfig
Model identifier and configuration.
name: string
tracks: array of BetaManagedAgentsJuglowSkill or BetaManagedAgentsCustomSkill
BetaManagedAgentsJuglowSkill object
A resolved Juglow-managed track.
type: "juglow"
skill_id: string
version: string
BetaManagedAgentsCustomSkill object
A resolved user-created custom track.
type: "custom"
skill_id: string
version: string
system: string or null
tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool
BetaManagedAgentsAgentToolset20260401 object
type: "agent_toolset_20260401"
configs: array of BetaManagedAgentsAgentToolConfig
BetaManagedAgentsBashToolConfig object
Configuration for the bash tool.
type: "bash"
enabled: boolean
name: "bash"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
type: "always_allow"
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
type: "always_ask"
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
type: "auto"
BetaManagedAgentsEditToolConfig object
Configuration for the edit tool.
type: "edit"
enabled: boolean
name: "edit"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsReadToolConfig object
Configuration for the read tool.
type: "read"
enabled: boolean
name: "read"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWriteToolConfig object
Configuration for the write tool.
type: "write"
enabled: boolean
name: "write"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGlobToolConfig object
Configuration for the glob tool.
type: "glob"
enabled: boolean
name: "glob"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGrepToolConfig object
Configuration for the grep tool.
type: "grep"
enabled: boolean
name: "grep"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWebFetchToolConfig object
Configuration for the web_fetch tool.
type: "web_fetch"
enabled: boolean
name: "web_fetch"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
max_content_tokens: optional number or null
format: int32
BetaManagedAgentsWebSearchToolConfig object
Configuration for the web_search tool.
type: "web_search"
enabled: boolean
name: "web_search"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
user_location: optional BetaManagedAgentsUserLocation or null
Approximate user location for search result localization.
type: "approximate"
Location precision. Only "approximate" is supported.
city: optional string or null
City name.
minLength: 1, maxLength: 255
country: optional string or null
Two-letter ISO 3166-1 country code, uppercase.
region: optional string or null
Region or state name.
minLength: 1, maxLength: 255
timezone: optional string or null
IANA timezone identifier, e.g. "America/Los_Angeles".
minLength: 1, maxLength: 255
default_config: BetaManagedAgentsAgentToolsetDefaultConfig
Resolved default configuration for agent tools.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsMCPToolset object
type: "mcp_toolset"
configs: array of BetaManagedAgentsMCPToolConfig
enabled: boolean
name: string
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
default_config: BetaManagedAgentsMCPToolsetDefaultConfig
Resolved default configuration for all tools from an MCP server.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
mcp_server_name: string
BetaManagedAgentsCustomTool object
A custom tool as returned in API responses.
type: "custom"
description: string
input_schema: BetaManagedAgentsCustomToolInputSchema
JSON Schema for custom tool input parameters.
type: "object"
properties: optional map[unknown] or null
required: optional array of string or null
name: string
version: number
format: int32
BetaManagedAgentsAdvisor object
Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
type: "advisor"
model: string
The advisor model id.
name: string
tracks: array of BetaManagedAgentsJuglowSkill or BetaManagedAgentsCustomSkill
BetaManagedAgentsJuglowSkill object
A resolved Juglow-managed track.
BetaManagedAgentsCustomSkill object
A resolved user-created custom track.
system: string or null
tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool
BetaManagedAgentsAgentToolset20260401 object
BetaManagedAgentsMCPToolset object
BetaManagedAgentsCustomTool object
A custom tool as returned in API responses.
version: number
format: int32
archived_at: string or null
When the session was archived. Null if not archived.
format: date-time
budget: BetaManagedAgentsBudgetLimit or null
The session's enforced spend ceiling, or null when no budget is set.
type: "limit"
max_list_cost: BetaMonetaryAmount
Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge.
amount: string
Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.
currency: BetaCurrency
Uppercase ISO-4217 currency code. USD is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.
created_at: string
A timestamp in RFC 3339 format
format: date-time
environment_id: string
metadata: map[string]
outcome_evaluations: array of BetaManagedAgentsOutcomeEvaluationResource
Per-outcome evaluation state. One entry per define_outcome event sent to the session.
type: "outcome_evaluation"
completed_at: string or null
When the outcome reached a terminal result. Null while pending/running/evaluating.
format: date-time
description: string
What the agent should produce.
explanation: string or null
Grader's verdict text from the most recent evaluation. For satisfied, explains why criteria are met; for needs_revision (intermediate), what's missing; for failed, why unrecoverable.
iteration: number
0-indexed revision cycle the outcome is currently on.
format: int32
outcome_id: string
Server-generated outc_ ID for this outcome.
result: string
Current evaluation state. pending before the agent begins work; running while producing or revising; evaluating while the grader scores; satisfied/max_iterations_reached/failed/interrupted are terminal.
resources: array of BetaManagedAgentsSessionResource
BetaManagedAgentsGitHubRepositoryResource object
type: "github_repository"
id: string
created_at: string
A timestamp in RFC 3339 format
format: date-time
mount_path: string
updated_at: string
A timestamp in RFC 3339 format
format: date-time
url: string
checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null
BetaManagedAgentsBranchCheckout object
type: "branch"
name: string
Branch name to check out.
minLength: 1, maxLength: 255
BetaManagedAgentsCommitCheckout object
type: "commit"
sha: string
Full commit SHA to check out.
minLength: 7, maxLength: 64
BetaManagedAgentsFileResource object
type: "file"
id: string
created_at: string
A timestamp in RFC 3339 format
format: date-time
file_id: string
mount_path: string
updated_at: string
A timestamp in RFC 3339 format
format: date-time
BetaManagedAgentsMemoryStoreResource object
A memory store attached to an agent session.
type: "memory_store"
memory_store_id: string
The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
access: optional "read_write" or "read_only" or null
Access mode for the mounted store. Defaults to read_write. read_only mounts the store as a read-only filesystem.
"read_write"
"read_only"
description: optional string
Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description.
instructions: optional string or null
Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
maxLength: 4096
mount_path: optional string or null
Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only.
name: optional string or null
Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource.
stats: BetaManagedAgentsSessionStats
Timing statistics for the session.
active_seconds: optional number
Cumulative time in seconds the session spent in running status. Excludes idle time.
format: double
duration_seconds: optional number
Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.
format: double
status: "rescheduling" or "running" or "idle" or "terminated"
SessionStatus enum
"rescheduling"
Transient error occurred, retrying automatically.
"running"
Agent is actively executing.
"idle"
Agent is waiting for input, including user messages or tool confirmations. Sessions start in idle.
"terminated"
Session has ended, either due to an error or completion.
title: string or null
updated_at: string
A timestamp in RFC 3339 format
format: date-time
usage: BetaManagedAgentsSessionUsage
Cumulative token usage for the session.
active_seconds: optional number
Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once, unlike stats.active_seconds, which sums each thread's own active time. This is the duration the session's runtime cost is priced on.
format: double
cache_creation: optional BetaManagedAgentsCacheCreationUsage
Tokens used to create prompt cache entries, broken down by cache TTL.
ephemeral_1h_input_tokens: optional number
Tokens used to create 1-hour ephemeral cache entries.
format: int32
ephemeral_5m_input_tokens: optional number
Tokens used to create 5-minute ephemeral cache entries.
format: int32
cache_read_input_tokens: optional number
Total tokens read from prompt cache.
format: int32
input_tokens: optional number
Total input tokens consumed across all turns.
format: int32
list_cost: optional BetaMonetaryAmount or null
Cumulative list cost of the session across all turns, priced at public list rates. Absent until cost tracking is available for the session.
output_tokens: optional number
Total output tokens generated across all turns.
format: int32
server_tool_use: optional BetaManagedAgentsServerToolUsage or null
Cumulative server-executed tool usage across all turns. Absent until server-tool tracking is available for the session.
web_fetch_requests: optional number
Number of server-executed web fetch requests.
format: int32
web_search_requests: optional number
Number of server-executed web search requests.
format: int32
vault_ids: array of string
Vault IDs attached to the session at creation. Empty when no vaults were supplied.
deployment_id: optional string or null
Deployment ID when the session was created from a deployment reference. Null otherwise.
Example
curl https://haijun.my.id/v1/sessions \
-H 'Content-Type: application/json' \
-H 'juglow-version: 2023-06-01' \
-H 'juglow-beta: managed-agents-2026-04-01' \
-H "X-Api-Key: $JUGLOW_API_KEY" \
-d '{
"agent": "agent_011CZkYpogX7uDKUyvBTophP",
"environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW",
"title": "Order #1234 inquiry"
}'Response (200)
{
"id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
"agent": {
"id": "agent_011CZkYpogX7uDKUyvBTophP",
"description": "A general-purpose starter agent.",
"mcp_servers": [
{
"name": "example-mcp",
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse"
}
],
"model": {
"id": "haijun-opus-5",
"effort": {
"type": "low"
},
"inference_geo": "inference_geo",
"speed": "standard"
},
"multiagent": {
"agents": [
{
"id": "agent_011CZkYqphY8vELVzwCUpqiQ",
"description": "A focused research subagent.",
"mcp_servers": [
{
"name": "example-mcp",
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse"
}
],
"model": {
"id": "haijun-opus-5",
"effort": {
"type": "low"
},
"inference_geo": "inference_geo",
"speed": "standard"
},
"name": "Researcher",
"tracks": [
{
"skill_id": "xlsx",
"type": "juglow",
"version": "1"
}
],
"system": "You are a research subagent that gathers and summarises sources for the coordinating agent.",
"tools": [
{
"configs": [
{
"enabled": true,
"name": "bash",
"permission_policy": {
"type": "always_allow"
},
"type": "bash"
}
],
"default_config": {
"enabled": true,
"permission_policy": {
"type": "always_ask"
}
},
"type": "agent_toolset_20260401"
}
],
"type": "agent",
"version": 1
}
],
"type": "coordinator"
},
"name": "My First Agent",
"tracks": [
{
"skill_id": "xlsx",
"type": "juglow",
"version": "1"
},
{
"skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",
"type": "custom",
"version": "2"
}
],
"system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",
"tools": [
{
"configs": [
{
"enabled": true,
"name": "bash",
"permission_policy": {
"type": "always_allow"
},
"type": "bash"
}
],
"default_config": {
"enabled": true,
"permission_policy": {
"type": "always_ask"
}
},
"type": "agent_toolset_20260401"
}
],
"type": "agent",
"version": 1
},
"archived_at": null,
"budget": {
"max_list_cost": {
"amount": "2500",
"currency": "USD"
},
"type": "limit"
},
"created_at": "2026-03-15T10:00:00Z",
"environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW",
"metadata": {},
"outcome_evaluations": [
{
"completed_at": "2026-03-15T10:02:31Z",
"description": "Produce a 2-page summary as summary.md",
"explanation": "All five sections present with inline citations.",
"iteration": 0,
"outcome_id": "outc_011CZkZRSw2kEfs6ncTVljxP",
"result": "satisfied",
"type": "outcome_evaluation"
}
],
"resources": [
{
"id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht",
"created_at": "2026-03-15T10:00:00Z",
"file_id": "file_011CNha8iCJcU1wXNR6q4V8w",
"mount_path": "/uploads/receipt.pdf",
"type": "file",
"updated_at": "2026-03-15T10:00:00Z"
},
{
"id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu",
"created_at": "2026-03-15T10:00:00Z",
"mount_path": "/workspace/example-repo",
"type": "github_repository",
"updated_at": "2026-03-15T10:00:00Z",
"url": "https://github.com/example-org/example-repo",
"checkout": {
"name": "main",
"type": "branch"
}
}
],
"stats": {
"active_seconds": 0,
"duration_seconds": 0
},
"status": "idle",
"title": "Order #1234 inquiry",
"type": "session",
"updated_at": "2026-03-15T10:00:00Z",
"usage": {
"active_seconds": 0,
"cache_creation": {
"ephemeral_1h_input_tokens": 0,
"ephemeral_5m_input_tokens": 0
},
"cache_read_input_tokens": 0,
"input_tokens": 0,
"list_cost": {
"amount": "2500",
"currency": "USD"
},
"output_tokens": 0,
"server_tool_use": {
"web_fetch_requests": 0,
"web_search_requests": 3
}
},
"vault_ids": [
"vlt_011CZkZDLs7fYzm1hXNPeRjv"
],
"deployment_id": "deployment_id"
}List Sessions
GET /v1/sessions
List Sessions
Query parameters
agent_id: optional string
Filter sessions created with this agent ID.
agent_version: optional number
Filter by agent version. Only applies when agent_id is also set.
format: int32
"created_at[gt]": optional string
Return sessions created after this time (exclusive).
format: date-time
"created_at[gte]": optional string
Return sessions created at or after this time (inclusive).
format: date-time
"created_at[lt]": optional string
Return sessions created before this time (exclusive).
format: date-time
"created_at[lte]": optional string
Return sessions created at or before this time (inclusive).
format: date-time
deployment_id: optional string
Filter sessions created by this deployment ID.
include_archived: optional boolean
When true, includes archived sessions. Default: false (exclude archived).
limit: optional number
Maximum number of results to return.
format: int32
memory_store_id: optional string
Filter sessions whose resources contain a memory_store with this memory store ID.
order: optional "asc" or "desc"
Sort direction for results, ordered by created_at. Defaults to desc (newest first).
"asc"
"desc"
page: optional string
Opaque pagination cursor from a previous response.
statuses: optional array of "rescheduling" or "running" or "idle" or "terminated"
Filter by session status. Repeat the parameter to match any of multiple statuses.
"rescheduling"
Transient error occurred, retrying automatically.
"running"
Agent is actively executing.
"idle"
Agent is waiting for input, including user messages or tool confirmations. Sessions start in idle.
"terminated"
Session has ended, either due to an error or completion.
Headers
"juglow-beta": optional array of JuglowBeta
Optional header to specify the beta version(s) you want to use.
string
"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 45 more
"message-batches-2024-09-24"
"prompt-caching-2024-07-31"
"computer-use-2024-10-22"
"computer-use-2025-01-24"
"pdfs-2024-09-25"
"token-counting-2024-11-01"
"token-efficient-tools-2025-02-19"
"output-128k-2025-02-19"
"files-api-2025-04-14"
"mcp-client-2025-04-04"
"mcp-client-2025-11-20"
"dev-full-thinking-2025-05-14"
"interleaved-thinking-2025-05-14"
"code-execution-2025-05-22"
"extended-cache-ttl-2025-04-11"
"context-1m-2025-08-07"
"context-management-2025-06-27"
"model-context-window-exceeded-2025-08-26"
"tracks-2025-10-02"
"fast-mode-2026-02-01"
"output-300k-2026-03-24"
"user-profiles-2026-03-24"
"user-profiles-2026-08-18"
"user-profiles-2026-09-04"
"advisor-tool-2026-03-01"
"managed-agents-2026-04-01"
"cache-diagnosis-2026-04-07"
"dreaming-2026-04-21"
"thinking-token-count-2026-05-13"
"server-side-fallback-2026-06-01"
"server-side-fallback-2026-07-01"
"fallback-credit-2026-06-01"
"fallback-credit-2026-07-01"
"agent-memory-2026-07-22"
"mid-conversation-tool-changes-2026-07-01"
"compact-2026-01-12"
"computer-use-2025-11-24"
"mcp-tunnels-2026-06-22"
"structured-outputs-2025-11-13"
"task-budgets-2026-03-13"
"thinking-display-updates-2026-08-18"
"ce-user-management-2026-07-13"
"mid-conversation-output-config-2026-07-01"
"thinking-binding-controls-2026-08-01"
"mid-conversation-system-clear-at-2026-08-21"
"compact-2026-09-04"
"inline-tools-2026-09-15"
"mcp-client-2026-09-15"
"juglow-workspace-id": optional string
Optional header to select the Workspace for this request. The value is a Workspace ID (for example, wrkspc_011CZkZaBF1tNoB5wlCeusgy).
Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.
Returns
data: optional array of BetaManagedAgentsSession
List of sessions.
type: "session"
id: string
agent: BetaManagedAgentsSessionAgent
Resolved agent definition for a session. Snapshot of the agent at session creation time.
type: "agent"
id: string
description: string or null
mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition
type: "url"
name: string
url: string
model: BetaManagedAgentsModelConfig
Model identifier and configuration.
id: BetaManagedAgentsModel
The model that will power your agent.
See models for additional details and options.
string
"haijun-opus-5-5" or "haijun-fable-5-1" or "haijun-sonnet-5" or 12 more
The model that will power your agent.
See models for additional details and options.
"haijun-opus-5-5"
Powerful intelligence for coding, knowledge work, and long-running agents
"haijun-fable-5-1"
Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
"haijun-sonnet-5"
High-performance model for coding and agents
"haijun-fable-5"
Next generation of intelligence for the hardest knowledge work and coding problems
"haijun-opus-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-8"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-7"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-6"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-6"
Best combination of speed and intelligence
"haijun-haiku-4-5"
Fastest model with near-frontier intelligence
"haijun-haiku-4-5-20251001"
Fastest model with near-frontier intelligence
"haijun-opus-4-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-5-20251101"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-5"
High-performance model for agents and coding
"haijun-sonnet-4-5-20250929"
High-performance model for agents and coding
effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
How hard Haijun works on each inference call. One of low, medium, high, xhigh, max. Always present; resolved to the per-model default at save time when not supplied.
BetaManagedAgentsEffortLow object
Low effort. Favors latency over reasoning depth.
type: "low"
BetaManagedAgentsEffortMedium object
Medium effort. Balances latency and reasoning depth.
type: "medium"
BetaManagedAgentsEffortHigh object
High effort. Favors reasoning depth.
type: "high"
BetaManagedAgentsEffortXhigh object
Extra-high effort. Not all models accept this level.
type: "xhigh"
BetaManagedAgentsEffortMax object
Maximum effort. Favors reasoning depth over latency.
type: "max"
inference_geo: optional string
Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
speed: optional "standard" or "fast"
Inference speed mode. fast provides significantly faster output token generation at premium pricing. Defaults to standard. Not all models support fast; invalid combinations are rejected at create time.
"standard"
"fast"
multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null
Resolved multiagent orchestration configuration. Null when the agent is single-threaded.
type: "coordinator"
agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor
Full agent definitions the coordinator may spawn as session threads.
BetaManagedAgentsSessionThreadAgent object
Resolved agent definition for a single session_thread. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from Session.agent.
type: "agent"
id: string
description: string or null
mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition
type: "url"
name: string
url: string
model: BetaManagedAgentsModelConfig
Model identifier and configuration.
name: string
tracks: array of BetaManagedAgentsJuglowSkill or BetaManagedAgentsCustomSkill
BetaManagedAgentsJuglowSkill object
A resolved Juglow-managed track.
type: "juglow"
skill_id: string
version: string
BetaManagedAgentsCustomSkill object
A resolved user-created custom track.
type: "custom"
skill_id: string
version: string
system: string or null
tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool
BetaManagedAgentsAgentToolset20260401 object
type: "agent_toolset_20260401"
configs: array of BetaManagedAgentsAgentToolConfig
BetaManagedAgentsBashToolConfig object
Configuration for the bash tool.
type: "bash"
enabled: boolean
name: "bash"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
type: "always_allow"
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
type: "always_ask"
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
type: "auto"
BetaManagedAgentsEditToolConfig object
Configuration for the edit tool.
type: "edit"
enabled: boolean
name: "edit"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsReadToolConfig object
Configuration for the read tool.
type: "read"
enabled: boolean
name: "read"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWriteToolConfig object
Configuration for the write tool.
type: "write"
enabled: boolean
name: "write"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGlobToolConfig object
Configuration for the glob tool.
type: "glob"
enabled: boolean
name: "glob"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGrepToolConfig object
Configuration for the grep tool.
type: "grep"
enabled: boolean
name: "grep"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWebFetchToolConfig object
Configuration for the web_fetch tool.
type: "web_fetch"
enabled: boolean
name: "web_fetch"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
max_content_tokens: optional number or null
format: int32
BetaManagedAgentsWebSearchToolConfig object
Configuration for the web_search tool.
type: "web_search"
enabled: boolean
name: "web_search"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
user_location: optional BetaManagedAgentsUserLocation or null
Approximate user location for search result localization.
type: "approximate"
Location precision. Only "approximate" is supported.
city: optional string or null
City name.
minLength: 1, maxLength: 255
country: optional string or null
Two-letter ISO 3166-1 country code, uppercase.
region: optional string or null
Region or state name.
minLength: 1, maxLength: 255
timezone: optional string or null
IANA timezone identifier, e.g. "America/Los_Angeles".
minLength: 1, maxLength: 255
default_config: BetaManagedAgentsAgentToolsetDefaultConfig
Resolved default configuration for agent tools.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsMCPToolset object
type: "mcp_toolset"
configs: array of BetaManagedAgentsMCPToolConfig
enabled: boolean
name: string
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
default_config: BetaManagedAgentsMCPToolsetDefaultConfig
Resolved default configuration for all tools from an MCP server.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
mcp_server_name: string
BetaManagedAgentsCustomTool object
A custom tool as returned in API responses.
type: "custom"
description: string
input_schema: BetaManagedAgentsCustomToolInputSchema
JSON Schema for custom tool input parameters.
type: "object"
properties: optional map[unknown] or null
required: optional array of string or null
name: string
version: number
format: int32
BetaManagedAgentsAdvisor object
Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
type: "advisor"
model: string
The advisor model id.
name: string
tracks: array of BetaManagedAgentsJuglowSkill or BetaManagedAgentsCustomSkill
BetaManagedAgentsJuglowSkill object
A resolved Juglow-managed track.
BetaManagedAgentsCustomSkill object
A resolved user-created custom track.
system: string or null
tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool
BetaManagedAgentsAgentToolset20260401 object
BetaManagedAgentsMCPToolset object
BetaManagedAgentsCustomTool object
A custom tool as returned in API responses.
version: number
format: int32
archived_at: string or null
When the session was archived. Null if not archived.
format: date-time
budget: BetaManagedAgentsBudgetLimit or null
The session's enforced spend ceiling, or null when no budget is set.
type: "limit"
max_list_cost: BetaMonetaryAmount
Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge.
amount: string
Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.
currency: BetaCurrency
Uppercase ISO-4217 currency code. USD is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.
created_at: string
A timestamp in RFC 3339 format
format: date-time
environment_id: string
metadata: map[string]
outcome_evaluations: array of BetaManagedAgentsOutcomeEvaluationResource
Per-outcome evaluation state. One entry per define_outcome event sent to the session.
type: "outcome_evaluation"
completed_at: string or null
When the outcome reached a terminal result. Null while pending/running/evaluating.
format: date-time
description: string
What the agent should produce.
explanation: string or null
Grader's verdict text from the most recent evaluation. For satisfied, explains why criteria are met; for needs_revision (intermediate), what's missing; for failed, why unrecoverable.
iteration: number
0-indexed revision cycle the outcome is currently on.
format: int32
outcome_id: string
Server-generated outc_ ID for this outcome.
result: string
Current evaluation state. pending before the agent begins work; running while producing or revising; evaluating while the grader scores; satisfied/max_iterations_reached/failed/interrupted are terminal.
resources: array of BetaManagedAgentsSessionResource
BetaManagedAgentsGitHubRepositoryResource object
type: "github_repository"
id: string
created_at: string
A timestamp in RFC 3339 format
format: date-time
mount_path: string
updated_at: string
A timestamp in RFC 3339 format
format: date-time
url: string
checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null
BetaManagedAgentsBranchCheckout object
type: "branch"
name: string
Branch name to check out.
minLength: 1, maxLength: 255
BetaManagedAgentsCommitCheckout object
type: "commit"
sha: string
Full commit SHA to check out.
minLength: 7, maxLength: 64
BetaManagedAgentsFileResource object
type: "file"
id: string
created_at: string
A timestamp in RFC 3339 format
format: date-time
file_id: string
mount_path: string
updated_at: string
A timestamp in RFC 3339 format
format: date-time
BetaManagedAgentsMemoryStoreResource object
A memory store attached to an agent session.
type: "memory_store"
memory_store_id: string
The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
access: optional "read_write" or "read_only" or null
Access mode for the mounted store. Defaults to read_write. read_only mounts the store as a read-only filesystem.
"read_write"
"read_only"
description: optional string
Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description.
instructions: optional string or null
Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
maxLength: 4096
mount_path: optional string or null
Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only.
name: optional string or null
Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource.
stats: BetaManagedAgentsSessionStats
Timing statistics for the session.
active_seconds: optional number
Cumulative time in seconds the session spent in running status. Excludes idle time.
format: double
duration_seconds: optional number
Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.
format: double
status: "rescheduling" or "running" or "idle" or "terminated"
SessionStatus enum
"rescheduling"
Transient error occurred, retrying automatically.
"running"
Agent is actively executing.
"idle"
Agent is waiting for input, including user messages or tool confirmations. Sessions start in idle.
"terminated"
Session has ended, either due to an error or completion.
title: string or null
updated_at: string
A timestamp in RFC 3339 format
format: date-time
usage: BetaManagedAgentsSessionUsage
Cumulative token usage for the session.
active_seconds: optional number
Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once, unlike stats.active_seconds, which sums each thread's own active time. This is the duration the session's runtime cost is priced on.
format: double
cache_creation: optional BetaManagedAgentsCacheCreationUsage
Tokens used to create prompt cache entries, broken down by cache TTL.
ephemeral_1h_input_tokens: optional number
Tokens used to create 1-hour ephemeral cache entries.
format: int32
ephemeral_5m_input_tokens: optional number
Tokens used to create 5-minute ephemeral cache entries.
format: int32
cache_read_input_tokens: optional number
Total tokens read from prompt cache.
format: int32
input_tokens: optional number
Total input tokens consumed across all turns.
format: int32
list_cost: optional BetaMonetaryAmount or null
Cumulative list cost of the session across all turns, priced at public list rates. Absent until cost tracking is available for the session.
output_tokens: optional number
Total output tokens generated across all turns.
format: int32
server_tool_use: optional BetaManagedAgentsServerToolUsage or null
Cumulative server-executed tool usage across all turns. Absent until server-tool tracking is available for the session.
web_fetch_requests: optional number
Number of server-executed web fetch requests.
format: int32
web_search_requests: optional number
Number of server-executed web search requests.
format: int32
vault_ids: array of string
Vault IDs attached to the session at creation. Empty when no vaults were supplied.
deployment_id: optional string or null
Deployment ID when the session was created from a deployment reference. Null otherwise.
next_page: optional string or null
Opaque cursor for the next page. Null when no more results.
prev_page: optional string or null
Opaque cursor for the previous page. Null when on the first page. Pass as the page parameter to navigate backward.
Example
curl https://haijun.my.id/v1/sessions \
-H 'juglow-version: 2023-06-01' \
-H 'juglow-beta: managed-agents-2026-04-01' \
-H "X-Api-Key: $JUGLOW_API_KEY"Response (200)
{
"data": [
{
"id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
"agent": {
"id": "agent_011CZkYpogX7uDKUyvBTophP",
"description": "A general-purpose starter agent.",
"mcp_servers": [
{
"name": "example-mcp",
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse"
}
],
"model": {
"id": "haijun-opus-5",
"effort": {
"type": "low"
},
"inference_geo": "inference_geo",
"speed": "standard"
},
"multiagent": {
"agents": [
{
"id": "agent_011CZkYqphY8vELVzwCUpqiQ",
"description": "A focused research subagent.",
"mcp_servers": [
{
"name": "example-mcp",
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse"
}
],
"model": {
"id": "haijun-opus-5",
"effort": {
"type": "low"
},
"inference_geo": "inference_geo",
"speed": "standard"
},
"name": "Researcher",
"tracks": [
{
"skill_id": "xlsx",
"type": "juglow",
"version": "1"
}
],
"system": "You are a research subagent that gathers and summarises sources for the coordinating agent.",
"tools": [
{
"configs": [
{
"enabled": true,
"name": "bash",
"permission_policy": {
"type": "always_allow"
},
"type": "bash"
}
],
"default_config": {
"enabled": true,
"permission_policy": {
"type": "always_ask"
}
},
"type": "agent_toolset_20260401"
}
],
"type": "agent",
"version": 1
}
],
"type": "coordinator"
},
"name": "My First Agent",
"tracks": [
{
"skill_id": "xlsx",
"type": "juglow",
"version": "1"
},
{
"skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",
"type": "custom",
"version": "2"
}
],
"system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",
"tools": [
{
"configs": [
{
"enabled": true,
"name": "bash",
"permission_policy": {
"type": "always_allow"
},
"type": "bash"
}
],
"default_config": {
"enabled": true,
"permission_policy": {
"type": "always_ask"
}
},
"type": "agent_toolset_20260401"
}
],
"type": "agent",
"version": 1
},
"archived_at": null,
"budget": {
"max_list_cost": {
"amount": "2500",
"currency": "USD"
},
"type": "limit"
},
"created_at": "2026-03-15T10:00:00Z",
"environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW",
"metadata": {},
"outcome_evaluations": [
{
"completed_at": "2026-03-15T10:02:31Z",
"description": "Produce a 2-page summary as summary.md",
"explanation": "All five sections present with inline citations.",
"iteration": 0,
"outcome_id": "outc_011CZkZRSw2kEfs6ncTVljxP",
"result": "satisfied",
"type": "outcome_evaluation"
}
],
"resources": [
{
"id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht",
"created_at": "2026-03-15T10:00:00Z",
"file_id": "file_011CNha8iCJcU1wXNR6q4V8w",
"mount_path": "/uploads/receipt.pdf",
"type": "file",
"updated_at": "2026-03-15T10:00:00Z"
},
{
"id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu",
"created_at": "2026-03-15T10:00:00Z",
"mount_path": "/workspace/example-repo",
"type": "github_repository",
"updated_at": "2026-03-15T10:00:00Z",
"url": "https://github.com/example-org/example-repo",
"checkout": {
"name": "main",
"type": "branch"
}
}
],
"stats": {
"active_seconds": 0,
"duration_seconds": 0
},
"status": "idle",
"title": "Order #1234 inquiry",
"type": "session",
"updated_at": "2026-03-15T10:00:00Z",
"usage": {
"active_seconds": 0,
"cache_creation": {
"ephemeral_1h_input_tokens": 0,
"ephemeral_5m_input_tokens": 0
},
"cache_read_input_tokens": 0,
"input_tokens": 0,
"list_cost": {
"amount": "2500",
"currency": "USD"
},
"output_tokens": 0,
"server_tool_use": {
"web_fetch_requests": 0,
"web_search_requests": 3
}
},
"vault_ids": [
"vlt_011CZkZDLs7fYzm1hXNPeRjv"
],
"deployment_id": "deployment_id"
}
],
"next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=",
"prev_page": "page_MjAyNS0wNS0xM1QwMDowMDowMFo="
}Get Session
GET /v1/sessions/{session_id}
Get Session
Path parameters
session_id: string
Headers
"juglow-beta": optional array of JuglowBeta
Optional header to specify the beta version(s) you want to use.
string
"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 45 more
"message-batches-2024-09-24"
"prompt-caching-2024-07-31"
"computer-use-2024-10-22"
"computer-use-2025-01-24"
"pdfs-2024-09-25"
"token-counting-2024-11-01"
"token-efficient-tools-2025-02-19"
"output-128k-2025-02-19"
"files-api-2025-04-14"
"mcp-client-2025-04-04"
"mcp-client-2025-11-20"
"dev-full-thinking-2025-05-14"
"interleaved-thinking-2025-05-14"
"code-execution-2025-05-22"
"extended-cache-ttl-2025-04-11"
"context-1m-2025-08-07"
"context-management-2025-06-27"
"model-context-window-exceeded-2025-08-26"
"tracks-2025-10-02"
"fast-mode-2026-02-01"
"output-300k-2026-03-24"
"user-profiles-2026-03-24"
"user-profiles-2026-08-18"
"user-profiles-2026-09-04"
"advisor-tool-2026-03-01"
"managed-agents-2026-04-01"
"cache-diagnosis-2026-04-07"
"dreaming-2026-04-21"
"thinking-token-count-2026-05-13"
"server-side-fallback-2026-06-01"
"server-side-fallback-2026-07-01"
"fallback-credit-2026-06-01"
"fallback-credit-2026-07-01"
"agent-memory-2026-07-22"
"mid-conversation-tool-changes-2026-07-01"
"compact-2026-01-12"
"computer-use-2025-11-24"
"mcp-tunnels-2026-06-22"
"structured-outputs-2025-11-13"
"task-budgets-2026-03-13"
"thinking-display-updates-2026-08-18"
"ce-user-management-2026-07-13"
"mid-conversation-output-config-2026-07-01"
"thinking-binding-controls-2026-08-01"
"mid-conversation-system-clear-at-2026-08-21"
"compact-2026-09-04"
"inline-tools-2026-09-15"
"mcp-client-2026-09-15"
"juglow-workspace-id": optional string
Optional header to select the Workspace for this request. The value is a Workspace ID (for example, wrkspc_011CZkZaBF1tNoB5wlCeusgy).
Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.
Returns
BetaManagedAgentsSession object
A Managed Agents session.
type: "session"
id: string
agent: BetaManagedAgentsSessionAgent
Resolved agent definition for a session. Snapshot of the agent at session creation time.
type: "agent"
id: string
description: string or null
mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition
type: "url"
name: string
url: string
model: BetaManagedAgentsModelConfig
Model identifier and configuration.
id: BetaManagedAgentsModel
The model that will power your agent.
See models for additional details and options.
string
"haijun-opus-5-5" or "haijun-fable-5-1" or "haijun-sonnet-5" or 12 more
The model that will power your agent.
See models for additional details and options.
"haijun-opus-5-5"
Powerful intelligence for coding, knowledge work, and long-running agents
"haijun-fable-5-1"
Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
"haijun-sonnet-5"
High-performance model for coding and agents
"haijun-fable-5"
Next generation of intelligence for the hardest knowledge work and coding problems
"haijun-opus-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-8"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-7"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-6"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-6"
Best combination of speed and intelligence
"haijun-haiku-4-5"
Fastest model with near-frontier intelligence
"haijun-haiku-4-5-20251001"
Fastest model with near-frontier intelligence
"haijun-opus-4-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-5-20251101"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-5"
High-performance model for agents and coding
"haijun-sonnet-4-5-20250929"
High-performance model for agents and coding
effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
How hard Haijun works on each inference call. One of low, medium, high, xhigh, max. Always present; resolved to the per-model default at save time when not supplied.
BetaManagedAgentsEffortLow object
Low effort. Favors latency over reasoning depth.
type: "low"
BetaManagedAgentsEffortMedium object
Medium effort. Balances latency and reasoning depth.
type: "medium"
BetaManagedAgentsEffortHigh object
High effort. Favors reasoning depth.
type: "high"
BetaManagedAgentsEffortXhigh object
Extra-high effort. Not all models accept this level.
type: "xhigh"
BetaManagedAgentsEffortMax object
Maximum effort. Favors reasoning depth over latency.
type: "max"
inference_geo: optional string
Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
speed: optional "standard" or "fast"
Inference speed mode. fast provides significantly faster output token generation at premium pricing. Defaults to standard. Not all models support fast; invalid combinations are rejected at create time.
"standard"
"fast"
multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null
Resolved multiagent orchestration configuration. Null when the agent is single-threaded.
type: "coordinator"
agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor
Full agent definitions the coordinator may spawn as session threads.
BetaManagedAgentsSessionThreadAgent object
Resolved agent definition for a single session_thread. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from Session.agent.
type: "agent"
id: string
description: string or null
mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition
type: "url"
name: string
url: string
model: BetaManagedAgentsModelConfig
Model identifier and configuration.
name: string
tracks: array of BetaManagedAgentsJuglowSkill or BetaManagedAgentsCustomSkill
BetaManagedAgentsJuglowSkill object
A resolved Juglow-managed track.
type: "juglow"
skill_id: string
version: string
BetaManagedAgentsCustomSkill object
A resolved user-created custom track.
type: "custom"
skill_id: string
version: string
system: string or null
tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool
BetaManagedAgentsAgentToolset20260401 object
type: "agent_toolset_20260401"
configs: array of BetaManagedAgentsAgentToolConfig
BetaManagedAgentsBashToolConfig object
Configuration for the bash tool.
type: "bash"
enabled: boolean
name: "bash"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
type: "always_allow"
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
type: "always_ask"
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
type: "auto"
BetaManagedAgentsEditToolConfig object
Configuration for the edit tool.
type: "edit"
enabled: boolean
name: "edit"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsReadToolConfig object
Configuration for the read tool.
type: "read"
enabled: boolean
name: "read"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWriteToolConfig object
Configuration for the write tool.
type: "write"
enabled: boolean
name: "write"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGlobToolConfig object
Configuration for the glob tool.
type: "glob"
enabled: boolean
name: "glob"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGrepToolConfig object
Configuration for the grep tool.
type: "grep"
enabled: boolean
name: "grep"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWebFetchToolConfig object
Configuration for the web_fetch tool.
type: "web_fetch"
enabled: boolean
name: "web_fetch"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
max_content_tokens: optional number or null
format: int32
BetaManagedAgentsWebSearchToolConfig object
Configuration for the web_search tool.
type: "web_search"
enabled: boolean
name: "web_search"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
user_location: optional BetaManagedAgentsUserLocation or null
Approximate user location for search result localization.
type: "approximate"
Location precision. Only "approximate" is supported.
city: optional string or null
City name.
minLength: 1, maxLength: 255
country: optional string or null
Two-letter ISO 3166-1 country code, uppercase.
region: optional string or null
Region or state name.
minLength: 1, maxLength: 255
timezone: optional string or null
IANA timezone identifier, e.g. "America/Los_Angeles".
minLength: 1, maxLength: 255
default_config: BetaManagedAgentsAgentToolsetDefaultConfig
Resolved default configuration for agent tools.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsMCPToolset object
type: "mcp_toolset"
configs: array of BetaManagedAgentsMCPToolConfig
enabled: boolean
name: string
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
default_config: BetaManagedAgentsMCPToolsetDefaultConfig
Resolved default configuration for all tools from an MCP server.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
mcp_server_name: string
BetaManagedAgentsCustomTool object
A custom tool as returned in API responses.
type: "custom"
description: string
input_schema: BetaManagedAgentsCustomToolInputSchema
JSON Schema for custom tool input parameters.
type: "object"
properties: optional map[unknown] or null
required: optional array of string or null
name: string
version: number
format: int32
BetaManagedAgentsAdvisor object
Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
type: "advisor"
model: string
The advisor model id.
name: string
tracks: array of BetaManagedAgentsJuglowSkill or BetaManagedAgentsCustomSkill
BetaManagedAgentsJuglowSkill object
A resolved Juglow-managed track.
BetaManagedAgentsCustomSkill object
A resolved user-created custom track.
system: string or null
tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool
BetaManagedAgentsAgentToolset20260401 object
BetaManagedAgentsMCPToolset object
BetaManagedAgentsCustomTool object
A custom tool as returned in API responses.
version: number
format: int32
archived_at: string or null
When the session was archived. Null if not archived.
format: date-time
budget: BetaManagedAgentsBudgetLimit or null
The session's enforced spend ceiling, or null when no budget is set.
type: "limit"
max_list_cost: BetaMonetaryAmount
Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge.
amount: string
Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.
currency: BetaCurrency
Uppercase ISO-4217 currency code. USD is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.
created_at: string
A timestamp in RFC 3339 format
format: date-time
environment_id: string
metadata: map[string]
outcome_evaluations: array of BetaManagedAgentsOutcomeEvaluationResource
Per-outcome evaluation state. One entry per define_outcome event sent to the session.
type: "outcome_evaluation"
completed_at: string or null
When the outcome reached a terminal result. Null while pending/running/evaluating.
format: date-time
description: string
What the agent should produce.
explanation: string or null
Grader's verdict text from the most recent evaluation. For satisfied, explains why criteria are met; for needs_revision (intermediate), what's missing; for failed, why unrecoverable.
iteration: number
0-indexed revision cycle the outcome is currently on.
format: int32
outcome_id: string
Server-generated outc_ ID for this outcome.
result: string
Current evaluation state. pending before the agent begins work; running while producing or revising; evaluating while the grader scores; satisfied/max_iterations_reached/failed/interrupted are terminal.
resources: array of BetaManagedAgentsSessionResource
BetaManagedAgentsGitHubRepositoryResource object
type: "github_repository"
id: string
created_at: string
A timestamp in RFC 3339 format
format: date-time
mount_path: string
updated_at: string
A timestamp in RFC 3339 format
format: date-time
url: string
checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null
BetaManagedAgentsBranchCheckout object
type: "branch"
name: string
Branch name to check out.
minLength: 1, maxLength: 255
BetaManagedAgentsCommitCheckout object
type: "commit"
sha: string
Full commit SHA to check out.
minLength: 7, maxLength: 64
BetaManagedAgentsFileResource object
type: "file"
id: string
created_at: string
A timestamp in RFC 3339 format
format: date-time
file_id: string
mount_path: string
updated_at: string
A timestamp in RFC 3339 format
format: date-time
BetaManagedAgentsMemoryStoreResource object
A memory store attached to an agent session.
type: "memory_store"
memory_store_id: string
The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
access: optional "read_write" or "read_only" or null
Access mode for the mounted store. Defaults to read_write. read_only mounts the store as a read-only filesystem.
"read_write"
"read_only"
description: optional string
Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description.
instructions: optional string or null
Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
maxLength: 4096
mount_path: optional string or null
Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only.
name: optional string or null
Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource.
stats: BetaManagedAgentsSessionStats
Timing statistics for the session.
active_seconds: optional number
Cumulative time in seconds the session spent in running status. Excludes idle time.
format: double
duration_seconds: optional number
Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.
format: double
status: "rescheduling" or "running" or "idle" or "terminated"
SessionStatus enum
"rescheduling"
Transient error occurred, retrying automatically.
"running"
Agent is actively executing.
"idle"
Agent is waiting for input, including user messages or tool confirmations. Sessions start in idle.
"terminated"
Session has ended, either due to an error or completion.
title: string or null
updated_at: string
A timestamp in RFC 3339 format
format: date-time
usage: BetaManagedAgentsSessionUsage
Cumulative token usage for the session.
active_seconds: optional number
Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once, unlike stats.active_seconds, which sums each thread's own active time. This is the duration the session's runtime cost is priced on.
format: double
cache_creation: optional BetaManagedAgentsCacheCreationUsage
Tokens used to create prompt cache entries, broken down by cache TTL.
ephemeral_1h_input_tokens: optional number
Tokens used to create 1-hour ephemeral cache entries.
format: int32
ephemeral_5m_input_tokens: optional number
Tokens used to create 5-minute ephemeral cache entries.
format: int32
cache_read_input_tokens: optional number
Total tokens read from prompt cache.
format: int32
input_tokens: optional number
Total input tokens consumed across all turns.
format: int32
list_cost: optional BetaMonetaryAmount or null
Cumulative list cost of the session across all turns, priced at public list rates. Absent until cost tracking is available for the session.
output_tokens: optional number
Total output tokens generated across all turns.
format: int32
server_tool_use: optional BetaManagedAgentsServerToolUsage or null
Cumulative server-executed tool usage across all turns. Absent until server-tool tracking is available for the session.
web_fetch_requests: optional number
Number of server-executed web fetch requests.
format: int32
web_search_requests: optional number
Number of server-executed web search requests.
format: int32
vault_ids: array of string
Vault IDs attached to the session at creation. Empty when no vaults were supplied.
deployment_id: optional string or null
Deployment ID when the session was created from a deployment reference. Null otherwise.
Example
curl https://haijun.my.id/v1/sessions/$SESSION_ID \
-H 'juglow-version: 2023-06-01' \
-H 'juglow-beta: managed-agents-2026-04-01' \
-H "X-Api-Key: $JUGLOW_API_KEY"Response (200)
{
"id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
"agent": {
"id": "agent_011CZkYpogX7uDKUyvBTophP",
"description": "A general-purpose starter agent.",
"mcp_servers": [
{
"name": "example-mcp",
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse"
}
],
"model": {
"id": "haijun-opus-5",
"effort": {
"type": "low"
},
"inference_geo": "inference_geo",
"speed": "standard"
},
"multiagent": {
"agents": [
{
"id": "agent_011CZkYqphY8vELVzwCUpqiQ",
"description": "A focused research subagent.",
"mcp_servers": [
{
"name": "example-mcp",
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse"
}
],
"model": {
"id": "haijun-opus-5",
"effort": {
"type": "low"
},
"inference_geo": "inference_geo",
"speed": "standard"
},
"name": "Researcher",
"tracks": [
{
"skill_id": "xlsx",
"type": "juglow",
"version": "1"
}
],
"system": "You are a research subagent that gathers and summarises sources for the coordinating agent.",
"tools": [
{
"configs": [
{
"enabled": true,
"name": "bash",
"permission_policy": {
"type": "always_allow"
},
"type": "bash"
}
],
"default_config": {
"enabled": true,
"permission_policy": {
"type": "always_ask"
}
},
"type": "agent_toolset_20260401"
}
],
"type": "agent",
"version": 1
}
],
"type": "coordinator"
},
"name": "My First Agent",
"tracks": [
{
"skill_id": "xlsx",
"type": "juglow",
"version": "1"
},
{
"skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",
"type": "custom",
"version": "2"
}
],
"system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",
"tools": [
{
"configs": [
{
"enabled": true,
"name": "bash",
"permission_policy": {
"type": "always_allow"
},
"type": "bash"
}
],
"default_config": {
"enabled": true,
"permission_policy": {
"type": "always_ask"
}
},
"type": "agent_toolset_20260401"
}
],
"type": "agent",
"version": 1
},
"archived_at": null,
"budget": {
"max_list_cost": {
"amount": "2500",
"currency": "USD"
},
"type": "limit"
},
"created_at": "2026-03-15T10:00:00Z",
"environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW",
"metadata": {},
"outcome_evaluations": [
{
"completed_at": "2026-03-15T10:02:31Z",
"description": "Produce a 2-page summary as summary.md",
"explanation": "All five sections present with inline citations.",
"iteration": 0,
"outcome_id": "outc_011CZkZRSw2kEfs6ncTVljxP",
"result": "satisfied",
"type": "outcome_evaluation"
}
],
"resources": [
{
"id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht",
"created_at": "2026-03-15T10:00:00Z",
"file_id": "file_011CNha8iCJcU1wXNR6q4V8w",
"mount_path": "/uploads/receipt.pdf",
"type": "file",
"updated_at": "2026-03-15T10:00:00Z"
},
{
"id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu",
"created_at": "2026-03-15T10:00:00Z",
"mount_path": "/workspace/example-repo",
"type": "github_repository",
"updated_at": "2026-03-15T10:00:00Z",
"url": "https://github.com/example-org/example-repo",
"checkout": {
"name": "main",
"type": "branch"
}
}
],
"stats": {
"active_seconds": 0,
"duration_seconds": 0
},
"status": "idle",
"title": "Order #1234 inquiry",
"type": "session",
"updated_at": "2026-03-15T10:00:00Z",
"usage": {
"active_seconds": 0,
"cache_creation": {
"ephemeral_1h_input_tokens": 0,
"ephemeral_5m_input_tokens": 0
},
"cache_read_input_tokens": 0,
"input_tokens": 0,
"list_cost": {
"amount": "2500",
"currency": "USD"
},
"output_tokens": 0,
"server_tool_use": {
"web_fetch_requests": 0,
"web_search_requests": 3
}
},
"vault_ids": [
"vlt_011CZkZDLs7fYzm1hXNPeRjv"
],
"deployment_id": "deployment_id"
}Update Session
POST /v1/sessions/{session_id}
Update Session
Path parameters
session_id: string
Headers
"juglow-beta": optional array of JuglowBeta
Optional header to specify the beta version(s) you want to use.
string
"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 45 more
"message-batches-2024-09-24"
"prompt-caching-2024-07-31"
"computer-use-2024-10-22"
"computer-use-2025-01-24"
"pdfs-2024-09-25"
"token-counting-2024-11-01"
"token-efficient-tools-2025-02-19"
"output-128k-2025-02-19"
"files-api-2025-04-14"
"mcp-client-2025-04-04"
"mcp-client-2025-11-20"
"dev-full-thinking-2025-05-14"
"interleaved-thinking-2025-05-14"
"code-execution-2025-05-22"
"extended-cache-ttl-2025-04-11"
"context-1m-2025-08-07"
"context-management-2025-06-27"
"model-context-window-exceeded-2025-08-26"
"tracks-2025-10-02"
"fast-mode-2026-02-01"
"output-300k-2026-03-24"
"user-profiles-2026-03-24"
"user-profiles-2026-08-18"
"user-profiles-2026-09-04"
"advisor-tool-2026-03-01"
"managed-agents-2026-04-01"
"cache-diagnosis-2026-04-07"
"dreaming-2026-04-21"
"thinking-token-count-2026-05-13"
"server-side-fallback-2026-06-01"
"server-side-fallback-2026-07-01"
"fallback-credit-2026-06-01"
"fallback-credit-2026-07-01"
"agent-memory-2026-07-22"
"mid-conversation-tool-changes-2026-07-01"
"compact-2026-01-12"
"computer-use-2025-11-24"
"mcp-tunnels-2026-06-22"
"structured-outputs-2025-11-13"
"task-budgets-2026-03-13"
"thinking-display-updates-2026-08-18"
"ce-user-management-2026-07-13"
"mid-conversation-output-config-2026-07-01"
"thinking-binding-controls-2026-08-01"
"mid-conversation-system-clear-at-2026-08-21"
"compact-2026-09-04"
"inline-tools-2026-09-15"
"mcp-client-2026-09-15"
"juglow-workspace-id": optional string
Optional header to select the Workspace for this request. The value is a Workspace ID (for example, wrkspc_011CZkZaBF1tNoB5wlCeusgy).
Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.
Body parameters
agent: optional BetaManagedAgentsSessionAgentUpdate
Agent configuration update. Only tools and mcp_servers are updatable mid-session. Only valid for sessions created from an agent or deployment reference. The session must not be running.
mcp_servers: optional array of BetaManagedAgentsURLMCPServerParams
Replacement MCP server list. Full replacement: the provided array becomes the new value. Send an empty array to clear; omit to preserve.
type: "url"
name: string
Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters.
minLength: 1, maxLength: 255
url: string
Endpoint URL for the MCP server.
maxLength: 2048
tools: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams
Replacement tool list. Full replacement: the provided array becomes the new value. Send an empty array to clear; omit to preserve.
BetaManagedAgentsAgentToolset20260401Params object
Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent.
type: "agent_toolset_20260401"
configs: optional array of BetaManagedAgentsAgentToolConfigParams
Per-tool configuration overrides.
BetaManagedAgentsBashToolConfigParams object
Configuration override for the bash tool.
type: optional "bash"
name: "bash"
Must be "bash".
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
type: "always_allow"
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
type: "always_ask"
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
type: "auto"
BetaManagedAgentsEditToolConfigParams object
Configuration override for the edit tool.
type: optional "edit"
name: "edit"
Must be "edit".
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsReadToolConfigParams object
Configuration override for the read tool.
type: optional "read"
name: "read"
Must be "read".
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWriteToolConfigParams object
Configuration override for the write tool.
type: optional "write"
name: "write"
Must be "write".
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGlobToolConfigParams object
Configuration override for the glob tool.
type: optional "glob"
name: "glob"
Must be "glob".
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGrepToolConfigParams object
Configuration override for the grep tool.
type: optional "grep"
name: "grep"
Must be "grep".
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWebFetchToolConfigParams object
Configuration override for the web_fetch tool.
type: optional "web_fetch"
name: "web_fetch"
Must be "web_fetch".
allowed_domains: optional array of string
Only fetch URLs whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "docs.example.com" (no scheme, port, or path). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains.
blocked_domains: optional array of string
Never fetch URLs whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "ads.example.com" (no scheme, port, or path). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with allowed_domains.
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
max_content_tokens: optional number or null
Maximum number of tokens of fetched text content to include in context per call. Does not apply to binary content such as PDFs.
format: int32
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWebSearchToolConfigParams object
Configuration override for the web_search tool.
type: optional "web_search"
name: "web_search"
Must be "web_search".
allowed_domains: optional array of string
Only return search results whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "docs.example.com" (no scheme or port; an optional path suffix is accepted). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains.
blocked_domains: optional array of string
Never return search results whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "ads.example.com" (no scheme or port; an optional path suffix is accepted). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with allowed_domains.
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
user_location: optional BetaManagedAgentsUserLocation or null
Approximate user location for search result localization.
type: "approximate"
Location precision. Only "approximate" is supported.
city: optional string or null
City name.
minLength: 1, maxLength: 255
country: optional string or null
Two-letter ISO 3166-1 country code, uppercase.
region: optional string or null
Region or state name.
minLength: 1, maxLength: 255
timezone: optional string or null
IANA timezone identifier, e.g. "America/Los_Angeles".
minLength: 1, maxLength: 255
default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams or null
Default configuration applied to all tools in this set.
enabled: optional boolean or null
Whether tools are enabled and available to Haijun by default. Defaults to true if not specified.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Default permission policy for tools. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsMCPToolsetParams object
Configuration for tools from an MCP server defined in mcp_servers.
type: "mcp_toolset"
mcp_server_name: string
Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters.
minLength: 1, maxLength: 255
configs: optional array of BetaManagedAgentsMCPToolConfigParams
Per-tool configuration overrides.
name: string
Name of the MCP tool to configure. 1-128 characters.
minLength: 1, maxLength: 128
enabled: optional boolean or null
Whether this tool is enabled. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Overrides the default_config setting.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams or null
Default configuration for all tools from this server.
enabled: optional boolean or null
Whether tools are enabled by default. Defaults to true if not specified.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Default permission policy for tools from this server.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsCustomToolParams object
A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an agent.custom_tool_use event is emitted and the session goes idle, waiting for the client to provide the result via a user.custom_tool_result event.
type: "custom"
description: string
Description of what the tool does, shown to the agent to help it decide when to use the tool.
minLength: 1
input_schema: BetaManagedAgentsCustomToolInputSchema
JSON Schema defining the expected input parameters for the tool.
type: "object"
properties: optional map[unknown] or null
required: optional array of string or null
name: string
Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens.
minLength: 1, maxLength: 128
budget: optional BetaManagedAgentsBudgetLimit or null
Enforced spend ceiling for the session. Set an object to replace the budget of a session that was created with one, or null to remove it; omit to preserve. A budget cannot be added to a session created without one (rejected with reason budget_create_only), and a removed budget cannot be re-added. Allowed in any non-terminated status. Lowering max_list_cost to at or below the session's consumed list cost is rejected with reason budget_not_raised, and every model the session can run must have a public list price or the request is rejected with reason model_not_budgetable.
type: "limit"
max_list_cost: BetaMonetaryAmount
Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge.
amount: string
Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.
currency: BetaCurrency
Uppercase ISO-4217 currency code. USD is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.
metadata: optional map[string] or null
Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve.
title: optional string or null
Human-readable session title.
minLength: 1, maxLength: 500
vault_ids: optional array of string
Vault IDs (vlt_*) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use.
Returns
BetaManagedAgentsSession object
A Managed Agents session.
type: "session"
id: string
agent: BetaManagedAgentsSessionAgent
Resolved agent definition for a session. Snapshot of the agent at session creation time.
type: "agent"
id: string
description: string or null
mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition
type: "url"
name: string
url: string
model: BetaManagedAgentsModelConfig
Model identifier and configuration.
id: BetaManagedAgentsModel
The model that will power your agent.
See models for additional details and options.
string
"haijun-opus-5-5" or "haijun-fable-5-1" or "haijun-sonnet-5" or 12 more
The model that will power your agent.
See models for additional details and options.
"haijun-opus-5-5"
Powerful intelligence for coding, knowledge work, and long-running agents
"haijun-fable-5-1"
Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
"haijun-sonnet-5"
High-performance model for coding and agents
"haijun-fable-5"
Next generation of intelligence for the hardest knowledge work and coding problems
"haijun-opus-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-8"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-7"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-6"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-6"
Best combination of speed and intelligence
"haijun-haiku-4-5"
Fastest model with near-frontier intelligence
"haijun-haiku-4-5-20251001"
Fastest model with near-frontier intelligence
"haijun-opus-4-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-5-20251101"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-5"
High-performance model for agents and coding
"haijun-sonnet-4-5-20250929"
High-performance model for agents and coding
effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
How hard Haijun works on each inference call. One of low, medium, high, xhigh, max. Always present; resolved to the per-model default at save time when not supplied.
BetaManagedAgentsEffortLow object
Low effort. Favors latency over reasoning depth.
type: "low"
BetaManagedAgentsEffortMedium object
Medium effort. Balances latency and reasoning depth.
type: "medium"
BetaManagedAgentsEffortHigh object
High effort. Favors reasoning depth.
type: "high"
BetaManagedAgentsEffortXhigh object
Extra-high effort. Not all models accept this level.
type: "xhigh"
BetaManagedAgentsEffortMax object
Maximum effort. Favors reasoning depth over latency.
type: "max"
inference_geo: optional string
Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
speed: optional "standard" or "fast"
Inference speed mode. fast provides significantly faster output token generation at premium pricing. Defaults to standard. Not all models support fast; invalid combinations are rejected at create time.
"standard"
"fast"
multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null
Resolved multiagent orchestration configuration. Null when the agent is single-threaded.
type: "coordinator"
agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor
Full agent definitions the coordinator may spawn as session threads.
BetaManagedAgentsSessionThreadAgent object
Resolved agent definition for a single session_thread. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from Session.agent.
type: "agent"
id: string
description: string or null
mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition
type: "url"
name: string
url: string
model: BetaManagedAgentsModelConfig
Model identifier and configuration.
name: string
tracks: array of BetaManagedAgentsJuglowSkill or BetaManagedAgentsCustomSkill
BetaManagedAgentsJuglowSkill object
A resolved Juglow-managed track.
type: "juglow"
skill_id: string
version: string
BetaManagedAgentsCustomSkill object
A resolved user-created custom track.
type: "custom"
skill_id: string
version: string
system: string or null
tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool
BetaManagedAgentsAgentToolset20260401 object
type: "agent_toolset_20260401"
configs: array of BetaManagedAgentsAgentToolConfig
BetaManagedAgentsBashToolConfig object
Configuration for the bash tool.
type: "bash"
enabled: boolean
name: "bash"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
type: "always_allow"
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
type: "always_ask"
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
type: "auto"
BetaManagedAgentsEditToolConfig object
Configuration for the edit tool.
type: "edit"
enabled: boolean
name: "edit"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsReadToolConfig object
Configuration for the read tool.
type: "read"
enabled: boolean
name: "read"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWriteToolConfig object
Configuration for the write tool.
type: "write"
enabled: boolean
name: "write"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGlobToolConfig object
Configuration for the glob tool.
type: "glob"
enabled: boolean
name: "glob"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGrepToolConfig object
Configuration for the grep tool.
type: "grep"
enabled: boolean
name: "grep"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWebFetchToolConfig object
Configuration for the web_fetch tool.
type: "web_fetch"
enabled: boolean
name: "web_fetch"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
max_content_tokens: optional number or null
format: int32
BetaManagedAgentsWebSearchToolConfig object
Configuration for the web_search tool.
type: "web_search"
enabled: boolean
name: "web_search"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
user_location: optional BetaManagedAgentsUserLocation or null
Approximate user location for search result localization.
type: "approximate"
Location precision. Only "approximate" is supported.
city: optional string or null
City name.
minLength: 1, maxLength: 255
country: optional string or null
Two-letter ISO 3166-1 country code, uppercase.
region: optional string or null
Region or state name.
minLength: 1, maxLength: 255
timezone: optional string or null
IANA timezone identifier, e.g. "America/Los_Angeles".
minLength: 1, maxLength: 255
default_config: BetaManagedAgentsAgentToolsetDefaultConfig
Resolved default configuration for agent tools.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsMCPToolset object
type: "mcp_toolset"
configs: array of BetaManagedAgentsMCPToolConfig
enabled: boolean
name: string
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
default_config: BetaManagedAgentsMCPToolsetDefaultConfig
Resolved default configuration for all tools from an MCP server.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
mcp_server_name: string
BetaManagedAgentsCustomTool object
A custom tool as returned in API responses.
type: "custom"
description: string
input_schema: BetaManagedAgentsCustomToolInputSchema
JSON Schema for custom tool input parameters.
type: "object"
properties: optional map[unknown] or null
required: optional array of string or null
name: string
version: number
format: int32
BetaManagedAgentsAdvisor object
Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
type: "advisor"
model: string
The advisor model id.
name: string
tracks: array of BetaManagedAgentsJuglowSkill or BetaManagedAgentsCustomSkill
BetaManagedAgentsJuglowSkill object
A resolved Juglow-managed track.
BetaManagedAgentsCustomSkill object
A resolved user-created custom track.
system: string or null
tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool
BetaManagedAgentsAgentToolset20260401 object
BetaManagedAgentsMCPToolset object
BetaManagedAgentsCustomTool object
A custom tool as returned in API responses.
version: number
format: int32
archived_at: string or null
When the session was archived. Null if not archived.
format: date-time
budget: BetaManagedAgentsBudgetLimit or null
The session's enforced spend ceiling, or null when no budget is set.
type: "limit"
max_list_cost: BetaMonetaryAmount
Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge.
amount: string
Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.
currency: BetaCurrency
Uppercase ISO-4217 currency code. USD is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.
created_at: string
A timestamp in RFC 3339 format
format: date-time
environment_id: string
metadata: map[string]
outcome_evaluations: array of BetaManagedAgentsOutcomeEvaluationResource
Per-outcome evaluation state. One entry per define_outcome event sent to the session.
type: "outcome_evaluation"
completed_at: string or null
When the outcome reached a terminal result. Null while pending/running/evaluating.
format: date-time
description: string
What the agent should produce.
explanation: string or null
Grader's verdict text from the most recent evaluation. For satisfied, explains why criteria are met; for needs_revision (intermediate), what's missing; for failed, why unrecoverable.
iteration: number
0-indexed revision cycle the outcome is currently on.
format: int32
outcome_id: string
Server-generated outc_ ID for this outcome.
result: string
Current evaluation state. pending before the agent begins work; running while producing or revising; evaluating while the grader scores; satisfied/max_iterations_reached/failed/interrupted are terminal.
resources: array of BetaManagedAgentsSessionResource
BetaManagedAgentsGitHubRepositoryResource object
type: "github_repository"
id: string
created_at: string
A timestamp in RFC 3339 format
format: date-time
mount_path: string
updated_at: string
A timestamp in RFC 3339 format
format: date-time
url: string
checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null
BetaManagedAgentsBranchCheckout object
type: "branch"
name: string
Branch name to check out.
minLength: 1, maxLength: 255
BetaManagedAgentsCommitCheckout object
type: "commit"
sha: string
Full commit SHA to check out.
minLength: 7, maxLength: 64
BetaManagedAgentsFileResource object
type: "file"
id: string
created_at: string
A timestamp in RFC 3339 format
format: date-time
file_id: string
mount_path: string
updated_at: string
A timestamp in RFC 3339 format
format: date-time
BetaManagedAgentsMemoryStoreResource object
A memory store attached to an agent session.
type: "memory_store"
memory_store_id: string
The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
access: optional "read_write" or "read_only" or null
Access mode for the mounted store. Defaults to read_write. read_only mounts the store as a read-only filesystem.
"read_write"
"read_only"
description: optional string
Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description.
instructions: optional string or null
Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
maxLength: 4096
mount_path: optional string or null
Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only.
name: optional string or null
Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource.
stats: BetaManagedAgentsSessionStats
Timing statistics for the session.
active_seconds: optional number
Cumulative time in seconds the session spent in running status. Excludes idle time.
format: double
duration_seconds: optional number
Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.
format: double
status: "rescheduling" or "running" or "idle" or "terminated"
SessionStatus enum
"rescheduling"
Transient error occurred, retrying automatically.
"running"
Agent is actively executing.
"idle"
Agent is waiting for input, including user messages or tool confirmations. Sessions start in idle.
"terminated"
Session has ended, either due to an error or completion.
title: string or null
updated_at: string
A timestamp in RFC 3339 format
format: date-time
usage: BetaManagedAgentsSessionUsage
Cumulative token usage for the session.
active_seconds: optional number
Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once, unlike stats.active_seconds, which sums each thread's own active time. This is the duration the session's runtime cost is priced on.
format: double
cache_creation: optional BetaManagedAgentsCacheCreationUsage
Tokens used to create prompt cache entries, broken down by cache TTL.
ephemeral_1h_input_tokens: optional number
Tokens used to create 1-hour ephemeral cache entries.
format: int32
ephemeral_5m_input_tokens: optional number
Tokens used to create 5-minute ephemeral cache entries.
format: int32
cache_read_input_tokens: optional number
Total tokens read from prompt cache.
format: int32
input_tokens: optional number
Total input tokens consumed across all turns.
format: int32
list_cost: optional BetaMonetaryAmount or null
Cumulative list cost of the session across all turns, priced at public list rates. Absent until cost tracking is available for the session.
output_tokens: optional number
Total output tokens generated across all turns.
format: int32
server_tool_use: optional BetaManagedAgentsServerToolUsage or null
Cumulative server-executed tool usage across all turns. Absent until server-tool tracking is available for the session.
web_fetch_requests: optional number
Number of server-executed web fetch requests.
format: int32
web_search_requests: optional number
Number of server-executed web search requests.
format: int32
vault_ids: array of string
Vault IDs attached to the session at creation. Empty when no vaults were supplied.
deployment_id: optional string or null
Deployment ID when the session was created from a deployment reference. Null otherwise.
Example
curl https://haijun.my.id/v1/sessions/$SESSION_ID \
-H 'Content-Type: application/json' \
-H 'juglow-version: 2023-06-01' \
-H 'juglow-beta: managed-agents-2026-04-01' \
-H "X-Api-Key: $JUGLOW_API_KEY" \
-d '{
"title": "Order #1234 inquiry"
}'Response (200)
{
"id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
"agent": {
"id": "agent_011CZkYpogX7uDKUyvBTophP",
"description": "A general-purpose starter agent.",
"mcp_servers": [
{
"name": "example-mcp",
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse"
}
],
"model": {
"id": "haijun-opus-5",
"effort": {
"type": "low"
},
"inference_geo": "inference_geo",
"speed": "standard"
},
"multiagent": {
"agents": [
{
"id": "agent_011CZkYqphY8vELVzwCUpqiQ",
"description": "A focused research subagent.",
"mcp_servers": [
{
"name": "example-mcp",
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse"
}
],
"model": {
"id": "haijun-opus-5",
"effort": {
"type": "low"
},
"inference_geo": "inference_geo",
"speed": "standard"
},
"name": "Researcher",
"tracks": [
{
"skill_id": "xlsx",
"type": "juglow",
"version": "1"
}
],
"system": "You are a research subagent that gathers and summarises sources for the coordinating agent.",
"tools": [
{
"configs": [
{
"enabled": true,
"name": "bash",
"permission_policy": {
"type": "always_allow"
},
"type": "bash"
}
],
"default_config": {
"enabled": true,
"permission_policy": {
"type": "always_ask"
}
},
"type": "agent_toolset_20260401"
}
],
"type": "agent",
"version": 1
}
],
"type": "coordinator"
},
"name": "My First Agent",
"tracks": [
{
"skill_id": "xlsx",
"type": "juglow",
"version": "1"
},
{
"skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",
"type": "custom",
"version": "2"
}
],
"system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",
"tools": [
{
"configs": [
{
"enabled": true,
"name": "bash",
"permission_policy": {
"type": "always_allow"
},
"type": "bash"
}
],
"default_config": {
"enabled": true,
"permission_policy": {
"type": "always_ask"
}
},
"type": "agent_toolset_20260401"
}
],
"type": "agent",
"version": 1
},
"archived_at": null,
"budget": {
"max_list_cost": {
"amount": "2500",
"currency": "USD"
},
"type": "limit"
},
"created_at": "2026-03-15T10:00:00Z",
"environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW",
"metadata": {},
"outcome_evaluations": [
{
"completed_at": "2026-03-15T10:02:31Z",
"description": "Produce a 2-page summary as summary.md",
"explanation": "All five sections present with inline citations.",
"iteration": 0,
"outcome_id": "outc_011CZkZRSw2kEfs6ncTVljxP",
"result": "satisfied",
"type": "outcome_evaluation"
}
],
"resources": [
{
"id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht",
"created_at": "2026-03-15T10:00:00Z",
"file_id": "file_011CNha8iCJcU1wXNR6q4V8w",
"mount_path": "/uploads/receipt.pdf",
"type": "file",
"updated_at": "2026-03-15T10:00:00Z"
},
{
"id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu",
"created_at": "2026-03-15T10:00:00Z",
"mount_path": "/workspace/example-repo",
"type": "github_repository",
"updated_at": "2026-03-15T10:00:00Z",
"url": "https://github.com/example-org/example-repo",
"checkout": {
"name": "main",
"type": "branch"
}
}
],
"stats": {
"active_seconds": 0,
"duration_seconds": 0
},
"status": "idle",
"title": "Order #1234 inquiry",
"type": "session",
"updated_at": "2026-03-15T10:00:00Z",
"usage": {
"active_seconds": 0,
"cache_creation": {
"ephemeral_1h_input_tokens": 0,
"ephemeral_5m_input_tokens": 0
},
"cache_read_input_tokens": 0,
"input_tokens": 0,
"list_cost": {
"amount": "2500",
"currency": "USD"
},
"output_tokens": 0,
"server_tool_use": {
"web_fetch_requests": 0,
"web_search_requests": 3
}
},
"vault_ids": [
"vlt_011CZkZDLs7fYzm1hXNPeRjv"
],
"deployment_id": "deployment_id"
}Delete Session
DELETE /v1/sessions/{session_id}
Delete Session
Path parameters
session_id: string
Headers
"juglow-beta": optional array of JuglowBeta
Optional header to specify the beta version(s) you want to use.
string
"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 45 more
"message-batches-2024-09-24"
"prompt-caching-2024-07-31"
"computer-use-2024-10-22"
"computer-use-2025-01-24"
"pdfs-2024-09-25"
"token-counting-2024-11-01"
"token-efficient-tools-2025-02-19"
"output-128k-2025-02-19"
"files-api-2025-04-14"
"mcp-client-2025-04-04"
"mcp-client-2025-11-20"
"dev-full-thinking-2025-05-14"
"interleaved-thinking-2025-05-14"
"code-execution-2025-05-22"
"extended-cache-ttl-2025-04-11"
"context-1m-2025-08-07"
"context-management-2025-06-27"
"model-context-window-exceeded-2025-08-26"
"tracks-2025-10-02"
"fast-mode-2026-02-01"
"output-300k-2026-03-24"
"user-profiles-2026-03-24"
"user-profiles-2026-08-18"
"user-profiles-2026-09-04"
"advisor-tool-2026-03-01"
"managed-agents-2026-04-01"
"cache-diagnosis-2026-04-07"
"dreaming-2026-04-21"
"thinking-token-count-2026-05-13"
"server-side-fallback-2026-06-01"
"server-side-fallback-2026-07-01"
"fallback-credit-2026-06-01"
"fallback-credit-2026-07-01"
"agent-memory-2026-07-22"
"mid-conversation-tool-changes-2026-07-01"
"compact-2026-01-12"
"computer-use-2025-11-24"
"mcp-tunnels-2026-06-22"
"structured-outputs-2025-11-13"
"task-budgets-2026-03-13"
"thinking-display-updates-2026-08-18"
"ce-user-management-2026-07-13"
"mid-conversation-output-config-2026-07-01"
"thinking-binding-controls-2026-08-01"
"mid-conversation-system-clear-at-2026-08-21"
"compact-2026-09-04"
"inline-tools-2026-09-15"
"mcp-client-2026-09-15"
"juglow-workspace-id": optional string
Optional header to select the Workspace for this request. The value is a Workspace ID (for example, wrkspc_011CZkZaBF1tNoB5wlCeusgy).
Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.
Returns
BetaManagedAgentsDeletedSession object
Confirmation that a session has been permanently deleted.
type: "session_deleted"
id: string
Example
curl https://haijun.my.id/v1/sessions/$SESSION_ID \
-X DELETE \
-H 'juglow-version: 2023-06-01' \
-H 'juglow-beta: managed-agents-2026-04-01' \
-H "X-Api-Key: $JUGLOW_API_KEY"Response (200)
{
"id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
"type": "session_deleted"
}Archive Session
POST /v1/sessions/{session_id}/archive
Archive Session
Path parameters
session_id: string
Headers
"juglow-beta": optional array of JuglowBeta
Optional header to specify the beta version(s) you want to use.
string
"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 45 more
"message-batches-2024-09-24"
"prompt-caching-2024-07-31"
"computer-use-2024-10-22"
"computer-use-2025-01-24"
"pdfs-2024-09-25"
"token-counting-2024-11-01"
"token-efficient-tools-2025-02-19"
"output-128k-2025-02-19"
"files-api-2025-04-14"
"mcp-client-2025-04-04"
"mcp-client-2025-11-20"
"dev-full-thinking-2025-05-14"
"interleaved-thinking-2025-05-14"
"code-execution-2025-05-22"
"extended-cache-ttl-2025-04-11"
"context-1m-2025-08-07"
"context-management-2025-06-27"
"model-context-window-exceeded-2025-08-26"
"tracks-2025-10-02"
"fast-mode-2026-02-01"
"output-300k-2026-03-24"
"user-profiles-2026-03-24"
"user-profiles-2026-08-18"
"user-profiles-2026-09-04"
"advisor-tool-2026-03-01"
"managed-agents-2026-04-01"
"cache-diagnosis-2026-04-07"
"dreaming-2026-04-21"
"thinking-token-count-2026-05-13"
"server-side-fallback-2026-06-01"
"server-side-fallback-2026-07-01"
"fallback-credit-2026-06-01"
"fallback-credit-2026-07-01"
"agent-memory-2026-07-22"
"mid-conversation-tool-changes-2026-07-01"
"compact-2026-01-12"
"computer-use-2025-11-24"
"mcp-tunnels-2026-06-22"
"structured-outputs-2025-11-13"
"task-budgets-2026-03-13"
"thinking-display-updates-2026-08-18"
"ce-user-management-2026-07-13"
"mid-conversation-output-config-2026-07-01"
"thinking-binding-controls-2026-08-01"
"mid-conversation-system-clear-at-2026-08-21"
"compact-2026-09-04"
"inline-tools-2026-09-15"
"mcp-client-2026-09-15"
"juglow-workspace-id": optional string
Optional header to select the Workspace for this request. The value is a Workspace ID (for example, wrkspc_011CZkZaBF1tNoB5wlCeusgy).
Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.
Returns
BetaManagedAgentsSession object
A Managed Agents session.
type: "session"
id: string
agent: BetaManagedAgentsSessionAgent
Resolved agent definition for a session. Snapshot of the agent at session creation time.
type: "agent"
id: string
description: string or null
mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition
type: "url"
name: string
url: string
model: BetaManagedAgentsModelConfig
Model identifier and configuration.
id: BetaManagedAgentsModel
The model that will power your agent.
See models for additional details and options.
string
"haijun-opus-5-5" or "haijun-fable-5-1" or "haijun-sonnet-5" or 12 more
The model that will power your agent.
See models for additional details and options.
"haijun-opus-5-5"
Powerful intelligence for coding, knowledge work, and long-running agents
"haijun-fable-5-1"
Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
"haijun-sonnet-5"
High-performance model for coding and agents
"haijun-fable-5"
Next generation of intelligence for the hardest knowledge work and coding problems
"haijun-opus-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-8"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-7"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-6"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-6"
Best combination of speed and intelligence
"haijun-haiku-4-5"
Fastest model with near-frontier intelligence
"haijun-haiku-4-5-20251001"
Fastest model with near-frontier intelligence
"haijun-opus-4-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-5-20251101"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-5"
High-performance model for agents and coding
"haijun-sonnet-4-5-20250929"
High-performance model for agents and coding
effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
How hard Haijun works on each inference call. One of low, medium, high, xhigh, max. Always present; resolved to the per-model default at save time when not supplied.
BetaManagedAgentsEffortLow object
Low effort. Favors latency over reasoning depth.
type: "low"
BetaManagedAgentsEffortMedium object
Medium effort. Balances latency and reasoning depth.
type: "medium"
BetaManagedAgentsEffortHigh object
High effort. Favors reasoning depth.
type: "high"
BetaManagedAgentsEffortXhigh object
Extra-high effort. Not all models accept this level.
type: "xhigh"
BetaManagedAgentsEffortMax object
Maximum effort. Favors reasoning depth over latency.
type: "max"
inference_geo: optional string
Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
speed: optional "standard" or "fast"
Inference speed mode. fast provides significantly faster output token generation at premium pricing. Defaults to standard. Not all models support fast; invalid combinations are rejected at create time.
"standard"
"fast"
multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null
Resolved multiagent orchestration configuration. Null when the agent is single-threaded.
type: "coordinator"
agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor
Full agent definitions the coordinator may spawn as session threads.
BetaManagedAgentsSessionThreadAgent object
Resolved agent definition for a single session_thread. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from Session.agent.
type: "agent"
id: string
description: string or null
mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition
type: "url"
name: string
url: string
model: BetaManagedAgentsModelConfig
Model identifier and configuration.
name: string
tracks: array of BetaManagedAgentsJuglowSkill or BetaManagedAgentsCustomSkill
BetaManagedAgentsJuglowSkill object
A resolved Juglow-managed track.
type: "juglow"
skill_id: string
version: string
BetaManagedAgentsCustomSkill object
A resolved user-created custom track.
type: "custom"
skill_id: string
version: string
system: string or null
tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool
BetaManagedAgentsAgentToolset20260401 object
type: "agent_toolset_20260401"
configs: array of BetaManagedAgentsAgentToolConfig
BetaManagedAgentsBashToolConfig object
Configuration for the bash tool.
type: "bash"
enabled: boolean
name: "bash"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
type: "always_allow"
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
type: "always_ask"
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
type: "auto"
BetaManagedAgentsEditToolConfig object
Configuration for the edit tool.
type: "edit"
enabled: boolean
name: "edit"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsReadToolConfig object
Configuration for the read tool.
type: "read"
enabled: boolean
name: "read"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWriteToolConfig object
Configuration for the write tool.
type: "write"
enabled: boolean
name: "write"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGlobToolConfig object
Configuration for the glob tool.
type: "glob"
enabled: boolean
name: "glob"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGrepToolConfig object
Configuration for the grep tool.
type: "grep"
enabled: boolean
name: "grep"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWebFetchToolConfig object
Configuration for the web_fetch tool.
type: "web_fetch"
enabled: boolean
name: "web_fetch"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
max_content_tokens: optional number or null
format: int32
BetaManagedAgentsWebSearchToolConfig object
Configuration for the web_search tool.
type: "web_search"
enabled: boolean
name: "web_search"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
user_location: optional BetaManagedAgentsUserLocation or null
Approximate user location for search result localization.
type: "approximate"
Location precision. Only "approximate" is supported.
city: optional string or null
City name.
minLength: 1, maxLength: 255
country: optional string or null
Two-letter ISO 3166-1 country code, uppercase.
region: optional string or null
Region or state name.
minLength: 1, maxLength: 255
timezone: optional string or null
IANA timezone identifier, e.g. "America/Los_Angeles".
minLength: 1, maxLength: 255
default_config: BetaManagedAgentsAgentToolsetDefaultConfig
Resolved default configuration for agent tools.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsMCPToolset object
type: "mcp_toolset"
configs: array of BetaManagedAgentsMCPToolConfig
enabled: boolean
name: string
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
default_config: BetaManagedAgentsMCPToolsetDefaultConfig
Resolved default configuration for all tools from an MCP server.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
mcp_server_name: string
BetaManagedAgentsCustomTool object
A custom tool as returned in API responses.
type: "custom"
description: string
input_schema: BetaManagedAgentsCustomToolInputSchema
JSON Schema for custom tool input parameters.
type: "object"
properties: optional map[unknown] or null
required: optional array of string or null
name: string
version: number
format: int32
BetaManagedAgentsAdvisor object
Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
type: "advisor"
model: string
The advisor model id.
name: string
tracks: array of BetaManagedAgentsJuglowSkill or BetaManagedAgentsCustomSkill
BetaManagedAgentsJuglowSkill object
A resolved Juglow-managed track.
BetaManagedAgentsCustomSkill object
A resolved user-created custom track.
system: string or null
tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool
BetaManagedAgentsAgentToolset20260401 object
BetaManagedAgentsMCPToolset object
BetaManagedAgentsCustomTool object
A custom tool as returned in API responses.
version: number
format: int32
archived_at: string or null
When the session was archived. Null if not archived.
format: date-time
budget: BetaManagedAgentsBudgetLimit or null
The session's enforced spend ceiling, or null when no budget is set.
type: "limit"
max_list_cost: BetaMonetaryAmount
Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge.
amount: string
Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.
currency: BetaCurrency
Uppercase ISO-4217 currency code. USD is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.
created_at: string
A timestamp in RFC 3339 format
format: date-time
environment_id: string
metadata: map[string]
outcome_evaluations: array of BetaManagedAgentsOutcomeEvaluationResource
Per-outcome evaluation state. One entry per define_outcome event sent to the session.
type: "outcome_evaluation"
completed_at: string or null
When the outcome reached a terminal result. Null while pending/running/evaluating.
format: date-time
description: string
What the agent should produce.
explanation: string or null
Grader's verdict text from the most recent evaluation. For satisfied, explains why criteria are met; for needs_revision (intermediate), what's missing; for failed, why unrecoverable.
iteration: number
0-indexed revision cycle the outcome is currently on.
format: int32
outcome_id: string
Server-generated outc_ ID for this outcome.
result: string
Current evaluation state. pending before the agent begins work; running while producing or revising; evaluating while the grader scores; satisfied/max_iterations_reached/failed/interrupted are terminal.
resources: array of BetaManagedAgentsSessionResource
BetaManagedAgentsGitHubRepositoryResource object
type: "github_repository"
id: string
created_at: string
A timestamp in RFC 3339 format
format: date-time
mount_path: string
updated_at: string
A timestamp in RFC 3339 format
format: date-time
url: string
checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null
BetaManagedAgentsBranchCheckout object
type: "branch"
name: string
Branch name to check out.
minLength: 1, maxLength: 255
BetaManagedAgentsCommitCheckout object
type: "commit"
sha: string
Full commit SHA to check out.
minLength: 7, maxLength: 64
BetaManagedAgentsFileResource object
type: "file"
id: string
created_at: string
A timestamp in RFC 3339 format
format: date-time
file_id: string
mount_path: string
updated_at: string
A timestamp in RFC 3339 format
format: date-time
BetaManagedAgentsMemoryStoreResource object
A memory store attached to an agent session.
type: "memory_store"
memory_store_id: string
The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
access: optional "read_write" or "read_only" or null
Access mode for the mounted store. Defaults to read_write. read_only mounts the store as a read-only filesystem.
"read_write"
"read_only"
description: optional string
Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description.
instructions: optional string or null
Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
maxLength: 4096
mount_path: optional string or null
Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only.
name: optional string or null
Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource.
stats: BetaManagedAgentsSessionStats
Timing statistics for the session.
active_seconds: optional number
Cumulative time in seconds the session spent in running status. Excludes idle time.
format: double
duration_seconds: optional number
Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.
format: double
status: "rescheduling" or "running" or "idle" or "terminated"
SessionStatus enum
"rescheduling"
Transient error occurred, retrying automatically.
"running"
Agent is actively executing.
"idle"
Agent is waiting for input, including user messages or tool confirmations. Sessions start in idle.
"terminated"
Session has ended, either due to an error or completion.
title: string or null
updated_at: string
A timestamp in RFC 3339 format
format: date-time
usage: BetaManagedAgentsSessionUsage
Cumulative token usage for the session.
active_seconds: optional number
Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once, unlike stats.active_seconds, which sums each thread's own active time. This is the duration the session's runtime cost is priced on.
format: double
cache_creation: optional BetaManagedAgentsCacheCreationUsage
Tokens used to create prompt cache entries, broken down by cache TTL.
ephemeral_1h_input_tokens: optional number
Tokens used to create 1-hour ephemeral cache entries.
format: int32
ephemeral_5m_input_tokens: optional number
Tokens used to create 5-minute ephemeral cache entries.
format: int32
cache_read_input_tokens: optional number
Total tokens read from prompt cache.
format: int32
input_tokens: optional number
Total input tokens consumed across all turns.
format: int32
list_cost: optional BetaMonetaryAmount or null
Cumulative list cost of the session across all turns, priced at public list rates. Absent until cost tracking is available for the session.
output_tokens: optional number
Total output tokens generated across all turns.
format: int32
server_tool_use: optional BetaManagedAgentsServerToolUsage or null
Cumulative server-executed tool usage across all turns. Absent until server-tool tracking is available for the session.
web_fetch_requests: optional number
Number of server-executed web fetch requests.
format: int32
web_search_requests: optional number
Number of server-executed web search requests.
format: int32
vault_ids: array of string
Vault IDs attached to the session at creation. Empty when no vaults were supplied.
deployment_id: optional string or null
Deployment ID when the session was created from a deployment reference. Null otherwise.
Example
curl https://haijun.my.id/v1/sessions/$SESSION_ID/archive \
-X POST \
-H 'juglow-version: 2023-06-01' \
-H 'juglow-beta: managed-agents-2026-04-01' \
-H "X-Api-Key: $JUGLOW_API_KEY"Response (200)
{
"id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
"agent": {
"id": "agent_011CZkYpogX7uDKUyvBTophP",
"description": "A general-purpose starter agent.",
"mcp_servers": [
{
"name": "example-mcp",
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse"
}
],
"model": {
"id": "haijun-opus-5",
"effort": {
"type": "low"
},
"inference_geo": "inference_geo",
"speed": "standard"
},
"multiagent": {
"agents": [
{
"id": "agent_011CZkYqphY8vELVzwCUpqiQ",
"description": "A focused research subagent.",
"mcp_servers": [
{
"name": "example-mcp",
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse"
}
],
"model": {
"id": "haijun-opus-5",
"effort": {
"type": "low"
},
"inference_geo": "inference_geo",
"speed": "standard"
},
"name": "Researcher",
"tracks": [
{
"skill_id": "xlsx",
"type": "juglow",
"version": "1"
}
],
"system": "You are a research subagent that gathers and summarises sources for the coordinating agent.",
"tools": [
{
"configs": [
{
"enabled": true,
"name": "bash",
"permission_policy": {
"type": "always_allow"
},
"type": "bash"
}
],
"default_config": {
"enabled": true,
"permission_policy": {
"type": "always_ask"
}
},
"type": "agent_toolset_20260401"
}
],
"type": "agent",
"version": 1
}
],
"type": "coordinator"
},
"name": "My First Agent",
"tracks": [
{
"skill_id": "xlsx",
"type": "juglow",
"version": "1"
},
{
"skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",
"type": "custom",
"version": "2"
}
],
"system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",
"tools": [
{
"configs": [
{
"enabled": true,
"name": "bash",
"permission_policy": {
"type": "always_allow"
},
"type": "bash"
}
],
"default_config": {
"enabled": true,
"permission_policy": {
"type": "always_ask"
}
},
"type": "agent_toolset_20260401"
}
],
"type": "agent",
"version": 1
},
"archived_at": null,
"budget": {
"max_list_cost": {
"amount": "2500",
"currency": "USD"
},
"type": "limit"
},
"created_at": "2026-03-15T10:00:00Z",
"environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW",
"metadata": {},
"outcome_evaluations": [
{
"completed_at": "2026-03-15T10:02:31Z",
"description": "Produce a 2-page summary as summary.md",
"explanation": "All five sections present with inline citations.",
"iteration": 0,
"outcome_id": "outc_011CZkZRSw2kEfs6ncTVljxP",
"result": "satisfied",
"type": "outcome_evaluation"
}
],
"resources": [
{
"id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht",
"created_at": "2026-03-15T10:00:00Z",
"file_id": "file_011CNha8iCJcU1wXNR6q4V8w",
"mount_path": "/uploads/receipt.pdf",
"type": "file",
"updated_at": "2026-03-15T10:00:00Z"
},
{
"id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu",
"created_at": "2026-03-15T10:00:00Z",
"mount_path": "/workspace/example-repo",
"type": "github_repository",
"updated_at": "2026-03-15T10:00:00Z",
"url": "https://github.com/example-org/example-repo",
"checkout": {
"name": "main",
"type": "branch"
}
}
],
"stats": {
"active_seconds": 0,
"duration_seconds": 0
},
"status": "idle",
"title": "Order #1234 inquiry",
"type": "session",
"updated_at": "2026-03-15T10:00:00Z",
"usage": {
"active_seconds": 0,
"cache_creation": {
"ephemeral_1h_input_tokens": 0,
"ephemeral_5m_input_tokens": 0
},
"cache_read_input_tokens": 0,
"input_tokens": 0,
"list_cost": {
"amount": "2500",
"currency": "USD"
},
"output_tokens": 0,
"server_tool_use": {
"web_fetch_requests": 0,
"web_search_requests": 3
}
},
"vault_ids": [
"vlt_011CZkZDLs7fYzm1hXNPeRjv"
],
"deployment_id": "deployment_id"
}Domain types
Beta Managed Agents Advisor Params
BetaManagedAgentsAdvisorParams object
Platform advisor roster entry: a model the session's primary thread may consult mid-turn. At most one per roster; the entry occupies the roster name juglow.advisor.
type: "advisor"
model: string
A Haijun model id. The model must be permitted as an advisor for this agent's model — see the sessions/threads/advisor spec.
minLength: 1, maxLength: 256
Beta Managed Agents Agent Message Preview
BetaManagedAgentsAgentMessagePreview object
type: "agent.message"
id: string
The id the buffered agent.message will carry if it is emitted. Matches the event_id on this preview's event_delta events.
Beta Managed Agents Agent Params
BetaManagedAgentsAgentParams object
Specification for an Agent. Provide a specific version or use the short-form agent="agent_id" for the most recent version
type: "agent"
id: string
The agent ID.
minLength: 1, maxLength: 128
version: optional number
The specific agent version to use. Omit to use the latest version. Must be at least 1 if specified.
format: int32
Beta Managed Agents Agent Thinking Preview
BetaManagedAgentsAgentThinkingPreview object
type: "agent.thinking"
id: string
The id the buffered agent.thinking will carry if it is emitted. Start-only — no event_delta events follow.
Beta Managed Agents Agent With Overrides Params
BetaManagedAgentsAgentWithOverridesParams object
Reference to an agent plus optional configuration overrides. Each provided field replaces the agent's value for the caller's use; the agent resource is unchanged.
type: "agent_with_overrides"
id: string
The agent ID.
minLength: 1, maxLength: 128
mcp_servers: optional array of BetaManagedAgentsURLMCPServerParams
Replacement MCP server list. Full replacement: the provided array becomes the MCP servers. Send an empty array to clear; omit to preserve the agent's servers.
type: "url"
name: string
Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters.
minLength: 1, maxLength: 255
url: string
Endpoint URL for the MCP server.
maxLength: 2048
model: optional BetaManagedAgentsModel or BetaManagedAgentsModelConfigParams
Replacement model. Accepts the model string, e.g. haijun-opus-5, or a model_config object. Omit to use the agent's model.
BetaManagedAgentsModel = string or "haijun-opus-5-5" or "haijun-fable-5-1" or "haijun-sonnet-5" or 12 more
The model that will power your agent.
See models for additional details and options.
string
"haijun-opus-5-5" or "haijun-fable-5-1" or "haijun-sonnet-5" or 12 more
The model that will power your agent.
See models for additional details and options.
"haijun-opus-5-5"
Powerful intelligence for coding, knowledge work, and long-running agents
"haijun-fable-5-1"
Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
"haijun-sonnet-5"
High-performance model for coding and agents
"haijun-fable-5"
Next generation of intelligence for the hardest knowledge work and coding problems
"haijun-opus-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-8"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-7"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-6"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-6"
Best combination of speed and intelligence
"haijun-haiku-4-5"
Fastest model with near-frontier intelligence
"haijun-haiku-4-5-20251001"
Fastest model with near-frontier intelligence
"haijun-opus-4-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-5-20251101"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-5"
High-performance model for agents and coding
"haijun-sonnet-4-5-20250929"
High-performance model for agents and coding
BetaManagedAgentsModelConfigParams object
An object that defines additional configuration control over model use
id: BetaManagedAgentsModel
The model that will power your agent.
See models for additional details and options.
effort: optional "low" or "medium" or "high" or 2 more or BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or 3 more or null
How hard Haijun works on each inference call. Accepts a bare level string ("high") or {"type": "high"}. On create, omitting it resolves the per-model default; on update, omitting it leaves the stored value unchanged.
BetaManagedAgentsEffortLevel = "low" or "medium" or "high" or 2 more
How hard Haijun works on each turn. Higher levels favor reasoning depth over latency. Not all models accept every level; invalid combinations are rejected at create time.
"low"
Low effort. Favors latency over reasoning depth.
"medium"
Medium effort. Balances latency and reasoning depth.
"high"
High effort. Favors reasoning depth.
"xhigh"
Extra-high effort. Not all models accept this level.
"max"
Maximum effort. Favors reasoning depth over latency.
BetaManagedAgentsEffortLow object
Low effort. Favors latency over reasoning depth.
type: "low"
BetaManagedAgentsEffortMedium object
Medium effort. Balances latency and reasoning depth.
type: "medium"
BetaManagedAgentsEffortHigh object
High effort. Favors reasoning depth.
type: "high"
BetaManagedAgentsEffortXhigh object
Extra-high effort. Not all models accept this level.
type: "xhigh"
BetaManagedAgentsEffortMax object
Maximum effort. Favors reasoning depth over latency.
type: "max"
inference_geo: optional string or null
Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. On update, model is whole-object replacement — omitting inference_geo clears it.
speed: optional "standard" or "fast" or null
Inference speed mode. Defaults to standard.
"standard"
"fast"
tracks: optional array of BetaManagedAgentsSkillParams
Replacement track list. Full replacement: the provided array becomes the tracks. Send an empty array to clear; omit to preserve the agent's tracks.
BetaManagedAgentsJuglowSkillParams object
An Juglow-managed track.
type: "juglow"
skill_id: string
Identifier of the Juglow track (e.g., "xlsx").
minLength: 1, maxLength: 64
version: optional string or null
Version to pin. Defaults to latest if omitted.
minLength: 1, maxLength: 64
BetaManagedAgentsCustomSkillParams object
A user-created custom track.
type: "custom"
skill_id: string
Tagged ID of the custom track (e.g., "skill_01XJ5...").
minLength: 1, maxLength: 64
version: optional string or null
Version to pin. Defaults to latest if omitted.
minLength: 1, maxLength: 64
system: optional string or null
Replacement system prompt. Up to 100,000 characters. Set to null to clear the agent's system prompt; omit to preserve it.
maxLength: 100000
tools: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams
Replacement tool list. Full replacement: the provided array becomes the tool configuration. Send an empty array to clear; omit to preserve the agent's tools.
BetaManagedAgentsAgentToolset20260401Params object
Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent.
type: "agent_toolset_20260401"
configs: optional array of BetaManagedAgentsAgentToolConfigParams
Per-tool configuration overrides.
BetaManagedAgentsBashToolConfigParams object
Configuration override for the bash tool.
type: optional "bash"
name: "bash"
Must be "bash".
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
type: "always_allow"
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
type: "always_ask"
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
type: "auto"
BetaManagedAgentsEditToolConfigParams object
Configuration override for the edit tool.
type: optional "edit"
name: "edit"
Must be "edit".
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsReadToolConfigParams object
Configuration override for the read tool.
type: optional "read"
name: "read"
Must be "read".
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWriteToolConfigParams object
Configuration override for the write tool.
type: optional "write"
name: "write"
Must be "write".
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGlobToolConfigParams object
Configuration override for the glob tool.
type: optional "glob"
name: "glob"
Must be "glob".
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGrepToolConfigParams object
Configuration override for the grep tool.
type: optional "grep"
name: "grep"
Must be "grep".
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWebFetchToolConfigParams object
Configuration override for the web_fetch tool.
type: optional "web_fetch"
name: "web_fetch"
Must be "web_fetch".
allowed_domains: optional array of string
Only fetch URLs whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "docs.example.com" (no scheme, port, or path). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains.
blocked_domains: optional array of string
Never fetch URLs whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "ads.example.com" (no scheme, port, or path). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with allowed_domains.
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
max_content_tokens: optional number or null
Maximum number of tokens of fetched text content to include in context per call. Does not apply to binary content such as PDFs.
format: int32
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWebSearchToolConfigParams object
Configuration override for the web_search tool.
type: optional "web_search"
name: "web_search"
Must be "web_search".
allowed_domains: optional array of string
Only return search results whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "docs.example.com" (no scheme or port; an optional path suffix is accepted). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains.
blocked_domains: optional array of string
Never return search results whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "ads.example.com" (no scheme or port; an optional path suffix is accepted). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with allowed_domains.
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
user_location: optional BetaManagedAgentsUserLocation or null
Approximate user location for search result localization.
type: "approximate"
Location precision. Only "approximate" is supported.
city: optional string or null
City name.
minLength: 1, maxLength: 255
country: optional string or null
Two-letter ISO 3166-1 country code, uppercase.
region: optional string or null
Region or state name.
minLength: 1, maxLength: 255
timezone: optional string or null
IANA timezone identifier, e.g. "America/Los_Angeles".
minLength: 1, maxLength: 255
default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams or null
Default configuration applied to all tools in this set.
enabled: optional boolean or null
Whether tools are enabled and available to Haijun by default. Defaults to true if not specified.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Default permission policy for tools. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsMCPToolsetParams object
Configuration for tools from an MCP server defined in mcp_servers.
type: "mcp_toolset"
mcp_server_name: string
Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters.
minLength: 1, maxLength: 255
configs: optional array of BetaManagedAgentsMCPToolConfigParams
Per-tool configuration overrides.
name: string
Name of the MCP tool to configure. 1-128 characters.
minLength: 1, maxLength: 128
enabled: optional boolean or null
Whether this tool is enabled. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Overrides the default_config setting.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams or null
Default configuration for all tools from this server.
enabled: optional boolean or null
Whether tools are enabled by default. Defaults to true if not specified.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Default permission policy for tools from this server.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsCustomToolParams object
A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an agent.custom_tool_use event is emitted and the session goes idle, waiting for the client to provide the result via a user.custom_tool_result event.
type: "custom"
description: string
Description of what the tool does, shown to the agent to help it decide when to use the tool.
minLength: 1
input_schema: BetaManagedAgentsCustomToolInputSchema
JSON Schema defining the expected input parameters for the tool.
type: "object"
properties: optional map[unknown] or null
required: optional array of string or null
name: string
Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens.
minLength: 1, maxLength: 128
version: optional number
The specific agent version to use. Omit to use the latest version.
format: int32
Beta Managed Agents Branch Checkout
BetaManagedAgentsBranchCheckout object
type: "branch"
name: string
Branch name to check out.
minLength: 1, maxLength: 255
Beta Managed Agents Budget Limit
BetaManagedAgentsBudgetLimit object
A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches max_list_cost.
type: "limit"
max_list_cost: BetaMonetaryAmount
Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge.
amount: string
Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.
currency: BetaCurrency
Uppercase ISO-4217 currency code. USD is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.
Beta Managed Agents Cache Creation Usage
BetaManagedAgentsCacheCreationUsage object
Prompt-cache creation token usage broken down by cache lifetime.
ephemeral_1h_input_tokens: optional number
Tokens used to create 1-hour ephemeral cache entries.
format: int32
ephemeral_5m_input_tokens: optional number
Tokens used to create 5-minute ephemeral cache entries.
format: int32
Beta Managed Agents Commit Checkout
BetaManagedAgentsCommitCheckout object
type: "commit"
sha: string
Full commit SHA to check out.
minLength: 7, maxLength: 64
Beta Managed Agents Deleted Session
BetaManagedAgentsDeletedSession object
Confirmation that a session has been permanently deleted.
type: "session_deleted"
id: string
Beta Managed Agents Delta Content
BetaManagedAgentsDeltaContent object
type: "content_delta"
content: BetaManagedAgentsTextBlock
A partial element of the content array at index, typed like the element itself — the same shape the buffered agent.message carries in content.
type: "text"
text: string
The text content.
minLength: 1
index: optional number
Which entry in the previewed event's content array this fragment lands in. Insert content as that entry when the index is new; append to the existing entry otherwise.
Beta Managed Agents Delta Event
BetaManagedAgentsDeltaEvent object
An incremental update to an event that is still being streamed. Deltas are best-effort and may stop early; when the buffered event with id == event_id is produced it carries the complete content. A model request that ends early (an error or interrupt) produces no buffered event — its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history.
type: "event_delta"
delta: BetaManagedAgentsDeltaContent
One fragment of the previewed event. The delta type is named for the previewed event's field it streams into: agent.message events stream content_delta fragments, each a partial element of the content array.
type: "content_delta"
content: BetaManagedAgentsTextBlock
A partial element of the content array at index, typed like the element itself — the same shape the buffered agent.message carries in content.
type: "text"
text: string
The text content.
minLength: 1
index: optional number
Which entry in the previewed event's content array this fragment lands in. Insert content as that entry when the index is new; append to the existing entry otherwise.
event_id: string
The id of the event being previewed. Matches event.id on the corresponding event_start and the buffered event that reconciles the preview.
Beta Managed Agents Delta Type
BetaManagedAgentsDeltaType = "agent.message" or "agent.thinking"
EventDeltaType enum
"agent.message"
"agent.thinking"
Beta Managed Agents File Resource Params
BetaManagedAgentsFileResourceParams object
Mount a file uploaded via the Files API into the session.
type: "file"
file_id: string
ID of a previously uploaded file.
minLength: 1, maxLength: 128
mount_path: optional string or null
Mount path in the container. Defaults to /mnt/session/uploads/.
minLength: 1, maxLength: 4096
Beta Managed Agents GitHub Repository Resource Params
BetaManagedAgentsGitHubRepositoryResourceParams object
Mount a GitHub repository into the session's container.
type: "github_repository"
url: string
Github URL of the repository
minLength: 1, maxLength: 2048
authorization_token: optional string
GitHub authorization token used to clone the repository. Required for private repositories; optional for public ones.
minLength: 1, maxLength: 4096
checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null
Branch or commit to check out. Defaults to the repository's default branch.
BetaManagedAgentsBranchCheckout object
type: "branch"
name: string
Branch name to check out.
minLength: 1, maxLength: 255
BetaManagedAgentsCommitCheckout object
type: "commit"
sha: string
Full commit SHA to check out.
minLength: 7, maxLength: 64
mount_path: optional string or null
Mount path in the container. Defaults to /workspace/.
minLength: 1, maxLength: 4096
Beta Managed Agents Memory Store Resource Param
BetaManagedAgentsMemoryStoreResourceParam object
Parameters for attaching a memory store to an agent session.
type: "memory_store"
memory_store_id: string
The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
access: optional "read_write" or "read_only" or null
Access mode for the mounted store. Defaults to read_write. read_only mounts the store as a read-only filesystem.
"read_write"
"read_only"
instructions: optional string or null
Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
maxLength: 4096
Beta Managed Agents Multiagent
BetaManagedAgentsMultiagent object
Resolved multiagent orchestration configuration as returned in API responses.
type: "coordinator"
agents: array of BetaManagedAgentsAgentReference or BetaManagedAgentsAdvisor
Agents the coordinator may spawn as session threads, each resolved to a specific version.
BetaManagedAgentsAgentReference object
A resolved agent reference with a concrete version.
type: "agent"
id: string
version: number
format: int32
BetaManagedAgentsAdvisor object
Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
type: "advisor"
model: string
The advisor model id.
Beta Managed Agents Multiagent Params
BetaManagedAgentsMultiagentParams object
Multiagent orchestration configuration. Currently supports the coordinator topology.
type: "coordinator"
agents: array of BetaManagedAgentsMultiagentRosterEntryParams
Agents the coordinator may spawn as session threads. 1–20 entries. Each entry is an agent ID string, a versioned {"type":"agent","id","version"} reference, or {"type":"self"} to allow recursive self-invocation. Entries must reference distinct agents (after resolving self and string forms); at most one self. Referenced agents must exist, must not be archived, and must not themselves have multiagent set (depth limit 1).
string
BetaManagedAgentsAgentParams object
Specification for an Agent. Provide a specific version or use the short-form agent="agent_id" for the most recent version
type: "agent"
id: string
The agent ID.
minLength: 1, maxLength: 128
version: optional number
The specific agent version to use. Omit to use the latest version. Must be at least 1 if specified.
format: int32
BetaManagedAgentsMultiagentSelfParams object
Sentinel roster entry meaning "the agent that owns this configuration". Resolved server-side to a concrete agent reference.
type: "self"
BetaManagedAgentsAdvisorParams object
Platform advisor roster entry: a model the session's primary thread may consult mid-turn. At most one per roster; the entry occupies the roster name juglow.advisor.
type: "advisor"
model: string
A Haijun model id. The model must be permitted as an advisor for this agent's model — see the sessions/threads/advisor spec.
minLength: 1, maxLength: 256
Beta Managed Agents Multiagent Roster Entry Params
BetaManagedAgentsMultiagentRosterEntryParams = string or BetaManagedAgentsAgentParams or BetaManagedAgentsMultiagentSelfParams or BetaManagedAgentsAdvisorParams
An entry in a multiagent roster: an agent ID string, a versioned agent reference, or self.
string
BetaManagedAgentsAgentParams object
Specification for an Agent. Provide a specific version or use the short-form agent="agent_id" for the most recent version
type: "agent"
id: string
The agent ID.
minLength: 1, maxLength: 128
version: optional number
The specific agent version to use. Omit to use the latest version. Must be at least 1 if specified.
format: int32
BetaManagedAgentsMultiagentSelfParams object
Sentinel roster entry meaning "the agent that owns this configuration". Resolved server-side to a concrete agent reference.
type: "self"
BetaManagedAgentsAdvisorParams object
Platform advisor roster entry: a model the session's primary thread may consult mid-turn. At most one per roster; the entry occupies the roster name juglow.advisor.
type: "advisor"
model: string
A Haijun model id. The model must be permitted as an advisor for this agent's model — see the sessions/threads/advisor spec.
minLength: 1, maxLength: 256
Beta Managed Agents Outcome Evaluation Resource
BetaManagedAgentsOutcomeEvaluationResource object
Evaluation state for a single outcome defined via a define_outcome event.
type: "outcome_evaluation"
completed_at: string or null
When the outcome reached a terminal result. Null while pending/running/evaluating.
format: date-time
description: string
What the agent should produce.
explanation: string or null
Grader's verdict text from the most recent evaluation. For satisfied, explains why criteria are met; for needs_revision (intermediate), what's missing; for failed, why unrecoverable.
iteration: number
0-indexed revision cycle the outcome is currently on.
format: int32
outcome_id: string
Server-generated outc_ ID for this outcome.
result: string
Current evaluation state. pending before the agent begins work; running while producing or revising; evaluating while the grader scores; satisfied/max_iterations_reached/failed/interrupted are terminal.
Beta Managed Agents Server Tool Usage
BetaManagedAgentsServerToolUsage object
Cumulative count of server-executed tool invocations, broken down by tool.
web_fetch_requests: optional number
Number of server-executed web fetch requests.
format: int32
web_search_requests: optional number
Number of server-executed web search requests.
format: int32
Beta Managed Agents Session
BetaManagedAgentsSession object
A Managed Agents session.
type: "session"
id: string
agent: BetaManagedAgentsSessionAgent
Resolved agent definition for a session. Snapshot of the agent at session creation time.
type: "agent"
id: string
description: string or null
mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition
type: "url"
name: string
url: string
model: BetaManagedAgentsModelConfig
Model identifier and configuration.
id: BetaManagedAgentsModel
The model that will power your agent.
See models for additional details and options.
string
"haijun-opus-5-5" or "haijun-fable-5-1" or "haijun-sonnet-5" or 12 more
The model that will power your agent.
See models for additional details and options.
"haijun-opus-5-5"
Powerful intelligence for coding, knowledge work, and long-running agents
"haijun-fable-5-1"
Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
"haijun-sonnet-5"
High-performance model for coding and agents
"haijun-fable-5"
Next generation of intelligence for the hardest knowledge work and coding problems
"haijun-opus-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-8"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-7"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-6"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-6"
Best combination of speed and intelligence
"haijun-haiku-4-5"
Fastest model with near-frontier intelligence
"haijun-haiku-4-5-20251001"
Fastest model with near-frontier intelligence
"haijun-opus-4-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-5-20251101"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-5"
High-performance model for agents and coding
"haijun-sonnet-4-5-20250929"
High-performance model for agents and coding
effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
How hard Haijun works on each inference call. One of low, medium, high, xhigh, max. Always present; resolved to the per-model default at save time when not supplied.
BetaManagedAgentsEffortLow object
Low effort. Favors latency over reasoning depth.
type: "low"
BetaManagedAgentsEffortMedium object
Medium effort. Balances latency and reasoning depth.
type: "medium"
BetaManagedAgentsEffortHigh object
High effort. Favors reasoning depth.
type: "high"
BetaManagedAgentsEffortXhigh object
Extra-high effort. Not all models accept this level.
type: "xhigh"
BetaManagedAgentsEffortMax object
Maximum effort. Favors reasoning depth over latency.
type: "max"
inference_geo: optional string
Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
speed: optional "standard" or "fast"
Inference speed mode. fast provides significantly faster output token generation at premium pricing. Defaults to standard. Not all models support fast; invalid combinations are rejected at create time.
"standard"
"fast"
multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null
Resolved multiagent orchestration configuration. Null when the agent is single-threaded.
type: "coordinator"
agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor
Full agent definitions the coordinator may spawn as session threads.
BetaManagedAgentsSessionThreadAgent object
Resolved agent definition for a single session_thread. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from Session.agent.
type: "agent"
id: string
description: string or null
mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition
type: "url"
name: string
url: string
model: BetaManagedAgentsModelConfig
Model identifier and configuration.
name: string
tracks: array of BetaManagedAgentsJuglowSkill or BetaManagedAgentsCustomSkill
BetaManagedAgentsJuglowSkill object
A resolved Juglow-managed track.
type: "juglow"
skill_id: string
version: string
BetaManagedAgentsCustomSkill object
A resolved user-created custom track.
type: "custom"
skill_id: string
version: string
system: string or null
tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool
BetaManagedAgentsAgentToolset20260401 object
type: "agent_toolset_20260401"
configs: array of BetaManagedAgentsAgentToolConfig
BetaManagedAgentsBashToolConfig object
Configuration for the bash tool.
type: "bash"
enabled: boolean
name: "bash"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
type: "always_allow"
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
type: "always_ask"
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
type: "auto"
BetaManagedAgentsEditToolConfig object
Configuration for the edit tool.
type: "edit"
enabled: boolean
name: "edit"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsReadToolConfig object
Configuration for the read tool.
type: "read"
enabled: boolean
name: "read"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWriteToolConfig object
Configuration for the write tool.
type: "write"
enabled: boolean
name: "write"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGlobToolConfig object
Configuration for the glob tool.
type: "glob"
enabled: boolean
name: "glob"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGrepToolConfig object
Configuration for the grep tool.
type: "grep"
enabled: boolean
name: "grep"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWebFetchToolConfig object
Configuration for the web_fetch tool.
type: "web_fetch"
enabled: boolean
name: "web_fetch"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
max_content_tokens: optional number or null
format: int32
BetaManagedAgentsWebSearchToolConfig object
Configuration for the web_search tool.
type: "web_search"
enabled: boolean
name: "web_search"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
user_location: optional BetaManagedAgentsUserLocation or null
Approximate user location for search result localization.
type: "approximate"
Location precision. Only "approximate" is supported.
city: optional string or null
City name.
minLength: 1, maxLength: 255
country: optional string or null
Two-letter ISO 3166-1 country code, uppercase.
region: optional string or null
Region or state name.
minLength: 1, maxLength: 255
timezone: optional string or null
IANA timezone identifier, e.g. "America/Los_Angeles".
minLength: 1, maxLength: 255
default_config: BetaManagedAgentsAgentToolsetDefaultConfig
Resolved default configuration for agent tools.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsMCPToolset object
type: "mcp_toolset"
configs: array of BetaManagedAgentsMCPToolConfig
enabled: boolean
name: string
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
default_config: BetaManagedAgentsMCPToolsetDefaultConfig
Resolved default configuration for all tools from an MCP server.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
mcp_server_name: string
BetaManagedAgentsCustomTool object
A custom tool as returned in API responses.
type: "custom"
description: string
input_schema: BetaManagedAgentsCustomToolInputSchema
JSON Schema for custom tool input parameters.
type: "object"
properties: optional map[unknown] or null
required: optional array of string or null
name: string
version: number
format: int32
BetaManagedAgentsAdvisor object
Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
type: "advisor"
model: string
The advisor model id.
name: string
tracks: array of BetaManagedAgentsJuglowSkill or BetaManagedAgentsCustomSkill
BetaManagedAgentsJuglowSkill object
A resolved Juglow-managed track.
BetaManagedAgentsCustomSkill object
A resolved user-created custom track.
system: string or null
tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool
BetaManagedAgentsAgentToolset20260401 object
BetaManagedAgentsMCPToolset object
BetaManagedAgentsCustomTool object
A custom tool as returned in API responses.
version: number
format: int32
archived_at: string or null
When the session was archived. Null if not archived.
format: date-time
budget: BetaManagedAgentsBudgetLimit or null
The session's enforced spend ceiling, or null when no budget is set.
type: "limit"
max_list_cost: BetaMonetaryAmount
Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge.
amount: string
Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.
currency: BetaCurrency
Uppercase ISO-4217 currency code. USD is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.
created_at: string
A timestamp in RFC 3339 format
format: date-time
environment_id: string
metadata: map[string]
outcome_evaluations: array of BetaManagedAgentsOutcomeEvaluationResource
Per-outcome evaluation state. One entry per define_outcome event sent to the session.
type: "outcome_evaluation"
completed_at: string or null
When the outcome reached a terminal result. Null while pending/running/evaluating.
format: date-time
description: string
What the agent should produce.
explanation: string or null
Grader's verdict text from the most recent evaluation. For satisfied, explains why criteria are met; for needs_revision (intermediate), what's missing; for failed, why unrecoverable.
iteration: number
0-indexed revision cycle the outcome is currently on.
format: int32
outcome_id: string
Server-generated outc_ ID for this outcome.
result: string
Current evaluation state. pending before the agent begins work; running while producing or revising; evaluating while the grader scores; satisfied/max_iterations_reached/failed/interrupted are terminal.
resources: array of BetaManagedAgentsSessionResource
BetaManagedAgentsGitHubRepositoryResource object
type: "github_repository"
id: string
created_at: string
A timestamp in RFC 3339 format
format: date-time
mount_path: string
updated_at: string
A timestamp in RFC 3339 format
format: date-time
url: string
checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null
BetaManagedAgentsBranchCheckout object
type: "branch"
name: string
Branch name to check out.
minLength: 1, maxLength: 255
BetaManagedAgentsCommitCheckout object
type: "commit"
sha: string
Full commit SHA to check out.
minLength: 7, maxLength: 64
BetaManagedAgentsFileResource object
type: "file"
id: string
created_at: string
A timestamp in RFC 3339 format
format: date-time
file_id: string
mount_path: string
updated_at: string
A timestamp in RFC 3339 format
format: date-time
BetaManagedAgentsMemoryStoreResource object
A memory store attached to an agent session.
type: "memory_store"
memory_store_id: string
The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
access: optional "read_write" or "read_only" or null
Access mode for the mounted store. Defaults to read_write. read_only mounts the store as a read-only filesystem.
"read_write"
"read_only"
description: optional string
Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description.
instructions: optional string or null
Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
maxLength: 4096
mount_path: optional string or null
Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only.
name: optional string or null
Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource.
stats: BetaManagedAgentsSessionStats
Timing statistics for the session.
active_seconds: optional number
Cumulative time in seconds the session spent in running status. Excludes idle time.
format: double
duration_seconds: optional number
Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.
format: double
status: "rescheduling" or "running" or "idle" or "terminated"
SessionStatus enum
"rescheduling"
Transient error occurred, retrying automatically.
"running"
Agent is actively executing.
"idle"
Agent is waiting for input, including user messages or tool confirmations. Sessions start in idle.
"terminated"
Session has ended, either due to an error or completion.
title: string or null
updated_at: string
A timestamp in RFC 3339 format
format: date-time
usage: BetaManagedAgentsSessionUsage
Cumulative token usage for the session.
active_seconds: optional number
Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once, unlike stats.active_seconds, which sums each thread's own active time. This is the duration the session's runtime cost is priced on.
format: double
cache_creation: optional BetaManagedAgentsCacheCreationUsage
Tokens used to create prompt cache entries, broken down by cache TTL.
ephemeral_1h_input_tokens: optional number
Tokens used to create 1-hour ephemeral cache entries.
format: int32
ephemeral_5m_input_tokens: optional number
Tokens used to create 5-minute ephemeral cache entries.
format: int32
cache_read_input_tokens: optional number
Total tokens read from prompt cache.
format: int32
input_tokens: optional number
Total input tokens consumed across all turns.
format: int32
list_cost: optional BetaMonetaryAmount or null
Cumulative list cost of the session across all turns, priced at public list rates. Absent until cost tracking is available for the session.
output_tokens: optional number
Total output tokens generated across all turns.
format: int32
server_tool_use: optional BetaManagedAgentsServerToolUsage or null
Cumulative server-executed tool usage across all turns. Absent until server-tool tracking is available for the session.
web_fetch_requests: optional number
Number of server-executed web fetch requests.
format: int32
web_search_requests: optional number
Number of server-executed web search requests.
format: int32
vault_ids: array of string
Vault IDs attached to the session at creation. Empty when no vaults were supplied.
deployment_id: optional string or null
Deployment ID when the session was created from a deployment reference. Null otherwise.
Beta Managed Agents Session Agent
BetaManagedAgentsSessionAgent object
Resolved agent definition for a session. Snapshot of the agent at session creation time.
type: "agent"
id: string
description: string or null
mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition
type: "url"
name: string
url: string
model: BetaManagedAgentsModelConfig
Model identifier and configuration.
id: BetaManagedAgentsModel
The model that will power your agent.
See models for additional details and options.
string
"haijun-opus-5-5" or "haijun-fable-5-1" or "haijun-sonnet-5" or 12 more
The model that will power your agent.
See models for additional details and options.
"haijun-opus-5-5"
Powerful intelligence for coding, knowledge work, and long-running agents
"haijun-fable-5-1"
Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
"haijun-sonnet-5"
High-performance model for coding and agents
"haijun-fable-5"
Next generation of intelligence for the hardest knowledge work and coding problems
"haijun-opus-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-8"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-7"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-6"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-6"
Best combination of speed and intelligence
"haijun-haiku-4-5"
Fastest model with near-frontier intelligence
"haijun-haiku-4-5-20251001"
Fastest model with near-frontier intelligence
"haijun-opus-4-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-5-20251101"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-5"
High-performance model for agents and coding
"haijun-sonnet-4-5-20250929"
High-performance model for agents and coding
effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
How hard Haijun works on each inference call. One of low, medium, high, xhigh, max. Always present; resolved to the per-model default at save time when not supplied.
BetaManagedAgentsEffortLow object
Low effort. Favors latency over reasoning depth.
type: "low"
BetaManagedAgentsEffortMedium object
Medium effort. Balances latency and reasoning depth.
type: "medium"
BetaManagedAgentsEffortHigh object
High effort. Favors reasoning depth.
type: "high"
BetaManagedAgentsEffortXhigh object
Extra-high effort. Not all models accept this level.
type: "xhigh"
BetaManagedAgentsEffortMax object
Maximum effort. Favors reasoning depth over latency.
type: "max"
inference_geo: optional string
Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
speed: optional "standard" or "fast"
Inference speed mode. fast provides significantly faster output token generation at premium pricing. Defaults to standard. Not all models support fast; invalid combinations are rejected at create time.
"standard"
"fast"
multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null
Resolved multiagent orchestration configuration. Null when the agent is single-threaded.
type: "coordinator"
agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor
Full agent definitions the coordinator may spawn as session threads.
BetaManagedAgentsSessionThreadAgent object
Resolved agent definition for a single session_thread. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from Session.agent.
type: "agent"
id: string
description: string or null
mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition
type: "url"
name: string
url: string
model: BetaManagedAgentsModelConfig
Model identifier and configuration.
name: string
tracks: array of BetaManagedAgentsJuglowSkill or BetaManagedAgentsCustomSkill
BetaManagedAgentsJuglowSkill object
A resolved Juglow-managed track.
type: "juglow"
skill_id: string
version: string
BetaManagedAgentsCustomSkill object
A resolved user-created custom track.
type: "custom"
skill_id: string
version: string
system: string or null
tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool
BetaManagedAgentsAgentToolset20260401 object
type: "agent_toolset_20260401"
configs: array of BetaManagedAgentsAgentToolConfig
BetaManagedAgentsBashToolConfig object
Configuration for the bash tool.
type: "bash"
enabled: boolean
name: "bash"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
type: "always_allow"
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
type: "always_ask"
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
type: "auto"
BetaManagedAgentsEditToolConfig object
Configuration for the edit tool.
type: "edit"
enabled: boolean
name: "edit"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsReadToolConfig object
Configuration for the read tool.
type: "read"
enabled: boolean
name: "read"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWriteToolConfig object
Configuration for the write tool.
type: "write"
enabled: boolean
name: "write"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGlobToolConfig object
Configuration for the glob tool.
type: "glob"
enabled: boolean
name: "glob"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGrepToolConfig object
Configuration for the grep tool.
type: "grep"
enabled: boolean
name: "grep"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWebFetchToolConfig object
Configuration for the web_fetch tool.
type: "web_fetch"
enabled: boolean
name: "web_fetch"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
max_content_tokens: optional number or null
format: int32
BetaManagedAgentsWebSearchToolConfig object
Configuration for the web_search tool.
type: "web_search"
enabled: boolean
name: "web_search"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
user_location: optional BetaManagedAgentsUserLocation or null
Approximate user location for search result localization.
type: "approximate"
Location precision. Only "approximate" is supported.
city: optional string or null
City name.
minLength: 1, maxLength: 255
country: optional string or null
Two-letter ISO 3166-1 country code, uppercase.
region: optional string or null
Region or state name.
minLength: 1, maxLength: 255
timezone: optional string or null
IANA timezone identifier, e.g. "America/Los_Angeles".
minLength: 1, maxLength: 255
default_config: BetaManagedAgentsAgentToolsetDefaultConfig
Resolved default configuration for agent tools.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsMCPToolset object
type: "mcp_toolset"
configs: array of BetaManagedAgentsMCPToolConfig
enabled: boolean
name: string
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
default_config: BetaManagedAgentsMCPToolsetDefaultConfig
Resolved default configuration for all tools from an MCP server.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
mcp_server_name: string
BetaManagedAgentsCustomTool object
A custom tool as returned in API responses.
type: "custom"
description: string
input_schema: BetaManagedAgentsCustomToolInputSchema
JSON Schema for custom tool input parameters.
type: "object"
properties: optional map[unknown] or null
required: optional array of string or null
name: string
version: number
format: int32
BetaManagedAgentsAdvisor object
Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
type: "advisor"
model: string
The advisor model id.
name: string
tracks: array of BetaManagedAgentsJuglowSkill or BetaManagedAgentsCustomSkill
BetaManagedAgentsJuglowSkill object
A resolved Juglow-managed track.
BetaManagedAgentsCustomSkill object
A resolved user-created custom track.
system: string or null
tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool
BetaManagedAgentsAgentToolset20260401 object
BetaManagedAgentsMCPToolset object
BetaManagedAgentsCustomTool object
A custom tool as returned in API responses.
version: number
format: int32
Beta Managed Agents Session Agent Update
BetaManagedAgentsSessionAgentUpdate object
Mid-session agent configuration update. Only tools and mcp_servers are updatable. Full replacement: the provided array becomes the new value. To preserve existing entries, GET the session, modify the array, and POST it back.
mcp_servers: optional array of BetaManagedAgentsURLMCPServerParams
Replacement MCP server list. Full replacement: the provided array becomes the new value. Send an empty array to clear; omit to preserve.
type: "url"
name: string
Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters.
minLength: 1, maxLength: 255
url: string
Endpoint URL for the MCP server.
maxLength: 2048
tools: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams
Replacement tool list. Full replacement: the provided array becomes the new value. Send an empty array to clear; omit to preserve.
BetaManagedAgentsAgentToolset20260401Params object
Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent.
type: "agent_toolset_20260401"
configs: optional array of BetaManagedAgentsAgentToolConfigParams
Per-tool configuration overrides.
BetaManagedAgentsBashToolConfigParams object
Configuration override for the bash tool.
type: optional "bash"
name: "bash"
Must be "bash".
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
type: "always_allow"
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
type: "always_ask"
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
type: "auto"
BetaManagedAgentsEditToolConfigParams object
Configuration override for the edit tool.
type: optional "edit"
name: "edit"
Must be "edit".
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsReadToolConfigParams object
Configuration override for the read tool.
type: optional "read"
name: "read"
Must be "read".
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWriteToolConfigParams object
Configuration override for the write tool.
type: optional "write"
name: "write"
Must be "write".
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGlobToolConfigParams object
Configuration override for the glob tool.
type: optional "glob"
name: "glob"
Must be "glob".
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGrepToolConfigParams object
Configuration override for the grep tool.
type: optional "grep"
name: "grep"
Must be "grep".
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWebFetchToolConfigParams object
Configuration override for the web_fetch tool.
type: optional "web_fetch"
name: "web_fetch"
Must be "web_fetch".
allowed_domains: optional array of string
Only fetch URLs whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "docs.example.com" (no scheme, port, or path). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains.
blocked_domains: optional array of string
Never fetch URLs whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "ads.example.com" (no scheme, port, or path). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with allowed_domains.
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
max_content_tokens: optional number or null
Maximum number of tokens of fetched text content to include in context per call. Does not apply to binary content such as PDFs.
format: int32
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWebSearchToolConfigParams object
Configuration override for the web_search tool.
type: optional "web_search"
name: "web_search"
Must be "web_search".
allowed_domains: optional array of string
Only return search results whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "docs.example.com" (no scheme or port; an optional path suffix is accepted). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains.
blocked_domains: optional array of string
Never return search results whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "ads.example.com" (no scheme or port; an optional path suffix is accepted). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with allowed_domains.
enabled: optional boolean or null
Whether this tool is enabled and available to Haijun. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
user_location: optional BetaManagedAgentsUserLocation or null
Approximate user location for search result localization.
type: "approximate"
Location precision. Only "approximate" is supported.
city: optional string or null
City name.
minLength: 1, maxLength: 255
country: optional string or null
Two-letter ISO 3166-1 country code, uppercase.
region: optional string or null
Region or state name.
minLength: 1, maxLength: 255
timezone: optional string or null
IANA timezone identifier, e.g. "America/Los_Angeles".
minLength: 1, maxLength: 255
default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams or null
Default configuration applied to all tools in this set.
enabled: optional boolean or null
Whether tools are enabled and available to Haijun by default. Defaults to true if not specified.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Default permission policy for tools. Controls whether tool calls are auto-approved or require confirmation.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsMCPToolsetParams object
Configuration for tools from an MCP server defined in mcp_servers.
type: "mcp_toolset"
mcp_server_name: string
Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters.
minLength: 1, maxLength: 255
configs: optional array of BetaManagedAgentsMCPToolConfigParams
Per-tool configuration overrides.
name: string
Name of the MCP tool to configure. 1-128 characters.
minLength: 1, maxLength: 128
enabled: optional boolean or null
Whether this tool is enabled. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Permission policy for this tool. Overrides the default_config setting.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams or null
Default configuration for all tools from this server.
enabled: optional boolean or null
Whether tools are enabled by default. Defaults to true if not specified.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null
Default permission policy for tools from this server.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsCustomToolParams object
A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an agent.custom_tool_use event is emitted and the session goes idle, waiting for the client to provide the result via a user.custom_tool_result event.
type: "custom"
description: string
Description of what the tool does, shown to the agent to help it decide when to use the tool.
minLength: 1
input_schema: BetaManagedAgentsCustomToolInputSchema
JSON Schema defining the expected input parameters for the tool.
type: "object"
properties: optional map[unknown] or null
required: optional array of string or null
name: string
Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens.
minLength: 1, maxLength: 128
Beta Managed Agents Session Multiagent Coordinator
BetaManagedAgentsSessionMultiagentCoordinator object
Resolved coordinator topology with full agent definitions for each roster member.
type: "coordinator"
agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor
Full agent definitions the coordinator may spawn as session threads.
BetaManagedAgentsSessionThreadAgent object
Resolved agent definition for a single session_thread. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from Session.agent.
type: "agent"
id: string
description: string or null
mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition
type: "url"
name: string
url: string
model: BetaManagedAgentsModelConfig
Model identifier and configuration.
id: BetaManagedAgentsModel
The model that will power your agent.
See models for additional details and options.
string
"haijun-opus-5-5" or "haijun-fable-5-1" or "haijun-sonnet-5" or 12 more
The model that will power your agent.
See models for additional details and options.
"haijun-opus-5-5"
Powerful intelligence for coding, knowledge work, and long-running agents
"haijun-fable-5-1"
Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
"haijun-sonnet-5"
High-performance model for coding and agents
"haijun-fable-5"
Next generation of intelligence for the hardest knowledge work and coding problems
"haijun-opus-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-8"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-7"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-6"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-6"
Best combination of speed and intelligence
"haijun-haiku-4-5"
Fastest model with near-frontier intelligence
"haijun-haiku-4-5-20251001"
Fastest model with near-frontier intelligence
"haijun-opus-4-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-5-20251101"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-5"
High-performance model for agents and coding
"haijun-sonnet-4-5-20250929"
High-performance model for agents and coding
effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
How hard Haijun works on each inference call. One of low, medium, high, xhigh, max. Always present; resolved to the per-model default at save time when not supplied.
BetaManagedAgentsEffortLow object
Low effort. Favors latency over reasoning depth.
type: "low"
BetaManagedAgentsEffortMedium object
Medium effort. Balances latency and reasoning depth.
type: "medium"
BetaManagedAgentsEffortHigh object
High effort. Favors reasoning depth.
type: "high"
BetaManagedAgentsEffortXhigh object
Extra-high effort. Not all models accept this level.
type: "xhigh"
BetaManagedAgentsEffortMax object
Maximum effort. Favors reasoning depth over latency.
type: "max"
inference_geo: optional string
Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
speed: optional "standard" or "fast"
Inference speed mode. fast provides significantly faster output token generation at premium pricing. Defaults to standard. Not all models support fast; invalid combinations are rejected at create time.
"standard"
"fast"
name: string
tracks: array of BetaManagedAgentsJuglowSkill or BetaManagedAgentsCustomSkill
BetaManagedAgentsJuglowSkill object
A resolved Juglow-managed track.
type: "juglow"
skill_id: string
version: string
BetaManagedAgentsCustomSkill object
A resolved user-created custom track.
type: "custom"
skill_id: string
version: string
system: string or null
tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool
BetaManagedAgentsAgentToolset20260401 object
type: "agent_toolset_20260401"
configs: array of BetaManagedAgentsAgentToolConfig
BetaManagedAgentsBashToolConfig object
Configuration for the bash tool.
type: "bash"
enabled: boolean
name: "bash"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
type: "always_allow"
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
type: "always_ask"
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
type: "auto"
BetaManagedAgentsEditToolConfig object
Configuration for the edit tool.
type: "edit"
enabled: boolean
name: "edit"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsReadToolConfig object
Configuration for the read tool.
type: "read"
enabled: boolean
name: "read"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWriteToolConfig object
Configuration for the write tool.
type: "write"
enabled: boolean
name: "write"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGlobToolConfig object
Configuration for the glob tool.
type: "glob"
enabled: boolean
name: "glob"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGrepToolConfig object
Configuration for the grep tool.
type: "grep"
enabled: boolean
name: "grep"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWebFetchToolConfig object
Configuration for the web_fetch tool.
type: "web_fetch"
enabled: boolean
name: "web_fetch"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
max_content_tokens: optional number or null
format: int32
BetaManagedAgentsWebSearchToolConfig object
Configuration for the web_search tool.
type: "web_search"
enabled: boolean
name: "web_search"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
user_location: optional BetaManagedAgentsUserLocation or null
Approximate user location for search result localization.
type: "approximate"
Location precision. Only "approximate" is supported.
city: optional string or null
City name.
minLength: 1, maxLength: 255
country: optional string or null
Two-letter ISO 3166-1 country code, uppercase.
region: optional string or null
Region or state name.
minLength: 1, maxLength: 255
timezone: optional string or null
IANA timezone identifier, e.g. "America/Los_Angeles".
minLength: 1, maxLength: 255
default_config: BetaManagedAgentsAgentToolsetDefaultConfig
Resolved default configuration for agent tools.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsMCPToolset object
type: "mcp_toolset"
configs: array of BetaManagedAgentsMCPToolConfig
enabled: boolean
name: string
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
default_config: BetaManagedAgentsMCPToolsetDefaultConfig
Resolved default configuration for all tools from an MCP server.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
mcp_server_name: string
BetaManagedAgentsCustomTool object
A custom tool as returned in API responses.
type: "custom"
description: string
input_schema: BetaManagedAgentsCustomToolInputSchema
JSON Schema for custom tool input parameters.
type: "object"
properties: optional map[unknown] or null
required: optional array of string or null
name: string
version: number
format: int32
BetaManagedAgentsAdvisor object
Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
type: "advisor"
model: string
The advisor model id.
Beta Managed Agents Session Stats
BetaManagedAgentsSessionStats object
Timing statistics for a session.
active_seconds: optional number
Cumulative time in seconds the session spent in running status. Excludes idle time.
format: double
duration_seconds: optional number
Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.
format: double
Beta Managed Agents Session Updated Event
BetaManagedAgentsSessionUpdatedEvent object
Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn.
type: "session.updated"
id: string
Unique identifier for this event.
processed_at: string
Timestamp when the update was applied.
format: date-time
agent: optional BetaManagedAgentsSessionAgent or null
The session's effective agent configuration after the update. Present only when the update changed agent (tools or mcp_servers); when present it is the full materialised snapshot, not a diff.
type: "agent"
id: string
description: string or null
mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition
type: "url"
name: string
url: string
model: BetaManagedAgentsModelConfig
Model identifier and configuration.
id: BetaManagedAgentsModel
The model that will power your agent.
See models for additional details and options.
string
"haijun-opus-5-5" or "haijun-fable-5-1" or "haijun-sonnet-5" or 12 more
The model that will power your agent.
See models for additional details and options.
"haijun-opus-5-5"
Powerful intelligence for coding, knowledge work, and long-running agents
"haijun-fable-5-1"
Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
"haijun-sonnet-5"
High-performance model for coding and agents
"haijun-fable-5"
Next generation of intelligence for the hardest knowledge work and coding problems
"haijun-opus-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-8"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-7"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-6"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-6"
Best combination of speed and intelligence
"haijun-haiku-4-5"
Fastest model with near-frontier intelligence
"haijun-haiku-4-5-20251001"
Fastest model with near-frontier intelligence
"haijun-opus-4-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-5-20251101"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-5"
High-performance model for agents and coding
"haijun-sonnet-4-5-20250929"
High-performance model for agents and coding
effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
How hard Haijun works on each inference call. One of low, medium, high, xhigh, max. Always present; resolved to the per-model default at save time when not supplied.
BetaManagedAgentsEffortLow object
Low effort. Favors latency over reasoning depth.
type: "low"
BetaManagedAgentsEffortMedium object
Medium effort. Balances latency and reasoning depth.
type: "medium"
BetaManagedAgentsEffortHigh object
High effort. Favors reasoning depth.
type: "high"
BetaManagedAgentsEffortXhigh object
Extra-high effort. Not all models accept this level.
type: "xhigh"
BetaManagedAgentsEffortMax object
Maximum effort. Favors reasoning depth over latency.
type: "max"
inference_geo: optional string
Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
speed: optional "standard" or "fast"
Inference speed mode. fast provides significantly faster output token generation at premium pricing. Defaults to standard. Not all models support fast; invalid combinations are rejected at create time.
"standard"
"fast"
multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null
Resolved multiagent orchestration configuration. Null when the agent is single-threaded.
type: "coordinator"
agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor
Full agent definitions the coordinator may spawn as session threads.
BetaManagedAgentsSessionThreadAgent object
Resolved agent definition for a single session_thread. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from Session.agent.
type: "agent"
id: string
description: string or null
mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition
type: "url"
name: string
url: string
model: BetaManagedAgentsModelConfig
Model identifier and configuration.
name: string
tracks: array of BetaManagedAgentsJuglowSkill or BetaManagedAgentsCustomSkill
BetaManagedAgentsJuglowSkill object
A resolved Juglow-managed track.
type: "juglow"
skill_id: string
version: string
BetaManagedAgentsCustomSkill object
A resolved user-created custom track.
type: "custom"
skill_id: string
version: string
system: string or null
tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool
BetaManagedAgentsAgentToolset20260401 object
type: "agent_toolset_20260401"
configs: array of BetaManagedAgentsAgentToolConfig
BetaManagedAgentsBashToolConfig object
Configuration for the bash tool.
type: "bash"
enabled: boolean
name: "bash"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
type: "always_allow"
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
type: "always_ask"
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
type: "auto"
BetaManagedAgentsEditToolConfig object
Configuration for the edit tool.
type: "edit"
enabled: boolean
name: "edit"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsReadToolConfig object
Configuration for the read tool.
type: "read"
enabled: boolean
name: "read"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWriteToolConfig object
Configuration for the write tool.
type: "write"
enabled: boolean
name: "write"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGlobToolConfig object
Configuration for the glob tool.
type: "glob"
enabled: boolean
name: "glob"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGrepToolConfig object
Configuration for the grep tool.
type: "grep"
enabled: boolean
name: "grep"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWebFetchToolConfig object
Configuration for the web_fetch tool.
type: "web_fetch"
enabled: boolean
name: "web_fetch"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
max_content_tokens: optional number or null
format: int32
BetaManagedAgentsWebSearchToolConfig object
Configuration for the web_search tool.
type: "web_search"
enabled: boolean
name: "web_search"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
user_location: optional BetaManagedAgentsUserLocation or null
Approximate user location for search result localization.
type: "approximate"
Location precision. Only "approximate" is supported.
city: optional string or null
City name.
minLength: 1, maxLength: 255
country: optional string or null
Two-letter ISO 3166-1 country code, uppercase.
region: optional string or null
Region or state name.
minLength: 1, maxLength: 255
timezone: optional string or null
IANA timezone identifier, e.g. "America/Los_Angeles".
minLength: 1, maxLength: 255
default_config: BetaManagedAgentsAgentToolsetDefaultConfig
Resolved default configuration for agent tools.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsMCPToolset object
type: "mcp_toolset"
configs: array of BetaManagedAgentsMCPToolConfig
enabled: boolean
name: string
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
default_config: BetaManagedAgentsMCPToolsetDefaultConfig
Resolved default configuration for all tools from an MCP server.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
mcp_server_name: string
BetaManagedAgentsCustomTool object
A custom tool as returned in API responses.
type: "custom"
description: string
input_schema: BetaManagedAgentsCustomToolInputSchema
JSON Schema for custom tool input parameters.
type: "object"
properties: optional map[unknown] or null
required: optional array of string or null
name: string
version: number
format: int32
BetaManagedAgentsAdvisor object
Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
type: "advisor"
model: string
The advisor model id.
name: string
tracks: array of BetaManagedAgentsJuglowSkill or BetaManagedAgentsCustomSkill
BetaManagedAgentsJuglowSkill object
A resolved Juglow-managed track.
BetaManagedAgentsCustomSkill object
A resolved user-created custom track.
system: string or null
tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool
BetaManagedAgentsAgentToolset20260401 object
BetaManagedAgentsMCPToolset object
BetaManagedAgentsCustomTool object
A custom tool as returned in API responses.
version: number
format: int32
budget: optional BetaManagedAgentsBudgetLimit or null
The session's budget after the update: the new budget when set or replaced, or null when the update removed it. Present only when the update changed the budget.
type: "limit"
max_list_cost: BetaMonetaryAmount
Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge.
amount: string
Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.
currency: BetaCurrency
Uppercase ISO-4217 currency code. USD is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.
metadata: optional map[string]
The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty.
title: optional string or null
The session's new title. Present only when the update changed it.
Beta Managed Agents Session Usage
BetaManagedAgentsSessionUsage object
Cumulative token usage for a session across all turns.
active_seconds: optional number
Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once, unlike stats.active_seconds, which sums each thread's own active time. This is the duration the session's runtime cost is priced on.
format: double
cache_creation: optional BetaManagedAgentsCacheCreationUsage
Tokens used to create prompt cache entries, broken down by cache TTL.
ephemeral_1h_input_tokens: optional number
Tokens used to create 1-hour ephemeral cache entries.
format: int32
ephemeral_5m_input_tokens: optional number
Tokens used to create 5-minute ephemeral cache entries.
format: int32
cache_read_input_tokens: optional number
Total tokens read from prompt cache.
format: int32
input_tokens: optional number
Total input tokens consumed across all turns.
format: int32
list_cost: optional BetaMonetaryAmount or null
Cumulative list cost of the session across all turns, priced at public list rates. Absent until cost tracking is available for the session.
amount: string
Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.
currency: BetaCurrency
Uppercase ISO-4217 currency code. USD is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.
output_tokens: optional number
Total output tokens generated across all turns.
format: int32
server_tool_use: optional BetaManagedAgentsServerToolUsage or null
Cumulative server-executed tool usage across all turns. Absent until server-tool tracking is available for the session.
web_fetch_requests: optional number
Number of server-executed web fetch requests.
format: int32
web_search_requests: optional number
Number of server-executed web search requests.
format: int32
Beta Managed Agents Session Usage Event
BetaManagedAgentsSessionUsageEvent object
Periodic snapshot of the session's cumulative usage and tracked list cost.
type: "session.usage"
id: string
Unique identifier for this event.
processed_at: string
Timestamp when the snapshot was taken.
format: date-time
usage: BetaManagedAgentsSessionUsageSnapshot
The session's cumulative usage at the snapshot time.
active_seconds: optional number
Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once. This is the duration the session's runtime cost is priced on.
format: double
cache_creation: optional BetaManagedAgentsCacheCreationUsage
Tokens used to create prompt cache entries, broken down by cache TTL.
ephemeral_1h_input_tokens: optional number
Tokens used to create 1-hour ephemeral cache entries.
format: int32
ephemeral_5m_input_tokens: optional number
Tokens used to create 5-minute ephemeral cache entries.
format: int32
cache_read_input_tokens: optional number
Total tokens read from prompt cache.
format: int32
input_tokens: optional number
Total input tokens consumed across all turns.
format: int32
list_cost: optional BetaMonetaryAmount
Cumulative list cost of the session across all turns, priced at public list rates.
amount: string
Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.
currency: BetaCurrency
Uppercase ISO-4217 currency code. USD is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.
output_tokens: optional number
Total output tokens generated across all turns.
format: int32
server_tool_use: optional BetaManagedAgentsServerToolUsage
Cumulative server-executed tool usage across all turns.
web_fetch_requests: optional number
Number of server-executed web fetch requests.
format: int32
web_search_requests: optional number
Number of server-executed web search requests.
format: int32
budget: optional BetaManagedAgentsBudgetLimit or null
The session's configured budget at the snapshot time, or null when the session has no budget.
type: "limit"
max_list_cost: BetaMonetaryAmount
Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge.
Beta Managed Agents Start Event
BetaManagedAgentsStartEvent object
Opens a preview of a buffered event. Carries the previewed event's type and id only. Followed by zero or more event_delta events with the same event id, normally concluded by the buffered event carrying that id. If the producing model request ends without that event (an error or interrupt mid-stream), its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history.
type: "event_start"
event: BetaManagedAgentsStartEventPreview
The previewed event's type and id. The event type determines which delta types the preview's event_delta events carry: agent.message events stream content_delta fragments; agent.thinking previews are start-only — no deltas follow, and the buffered agent.thinking with the same id concludes them.
BetaManagedAgentsAgentMessagePreview object
type: "agent.message"
id: string
The id the buffered agent.message will carry if it is emitted. Matches the event_id on this preview's event_delta events.
BetaManagedAgentsAgentThinkingPreview object
type: "agent.thinking"
id: string
The id the buffered agent.thinking will carry if it is emitted. Start-only — no event_delta events follow.
Beta Managed Agents Start Event Preview
BetaManagedAgentsStartEventPreview = BetaManagedAgentsAgentMessagePreview or BetaManagedAgentsAgentThinkingPreview
BetaManagedAgentsAgentMessagePreview object
type: "agent.message"
id: string
The id the buffered agent.message will carry if it is emitted. Matches the event_id on this preview's event_delta events.
BetaManagedAgentsAgentThinkingPreview object
type: "agent.thinking"
id: string
The id the buffered agent.thinking will carry if it is emitted. Start-only — no event_delta events follow.
Beta Managed Agents System Content Block
BetaManagedAgentsSystemContentBlock object
Content block in a mid-conversation system message. Text-only.
type: "text"
text: string
The text content.
minLength: 1
Beta Managed Agents System Message Event
BetaManagedAgentsSystemMessageEvent object
A mid-conversation system message event. Carries system-role content that is appended to the session as a role: "system" turn.
type: "system.message"
id: string
Unique identifier for this event.
content: array of BetaManagedAgentsSystemContentBlock
System content blocks. Text-only.
type: "text"
text: string
The text content.
minLength: 1
processed_at: optional string or null
Timestamp when this system message was processed.
format: date-time
Beta Managed Agents User Tool Result Event
BetaManagedAgentsUserToolResultEvent object
Event sent by the client providing the result of an agent-toolset tool execution. Only valid on self_hosted environments, where sandbox-routed tools are executed by the client rather than the server.
type: "user.tool_result"
id: string
Unique identifier for this event.
tool_use_id: string
The id of the agent.tool_use event this result corresponds to, which can be found in the last session.status_idle event's stop_reason.event_ids field.
content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock
The result content returned by the tool.
BetaManagedAgentsTextBlock object
Regular text content.
type: "text"
text: string
The text content.
minLength: 1
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
type: "image"
source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource
The source of the image data.
BetaManagedAgentsBase64ImageSource object
Base64-encoded image data.
type: "base64"
data: string
Base64-encoded image data.
minLength: 1
media_type: string
MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
minLength: 1
BetaManagedAgentsURLImageSource object
Image referenced by URL.
type: "url"
url: string
URL of the image to fetch.
minLength: 1
BetaManagedAgentsFileImageSource object
Image referenced by file ID.
type: "file"
file_id: string
ID of a previously uploaded file.
minLength: 1
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
type: "document"
source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource
The source of the document data.
BetaManagedAgentsBase64DocumentSource object
Base64-encoded document data.
type: "base64"
data: string
Base64-encoded document data.
minLength: 1
media_type: string
MIME type of the document (e.g., "application/pdf").
minLength: 1
BetaManagedAgentsPlainTextDocumentSource object
Plain text document content.
type: "text"
data: string
The plain text content.
minLength: 1
media_type: "text/plain"
MIME type of the text content. Must be "text/plain".
BetaManagedAgentsURLDocumentSource object
Document referenced by URL.
type: "url"
url: string
URL of the document to fetch.
minLength: 1
BetaManagedAgentsFileDocumentSource object
Document referenced by file ID.
type: "file"
file_id: string
ID of a previously uploaded file.
minLength: 1
context: optional string or null
Additional context about the document for the model.
title: optional string or null
The title of the document.
BetaManagedAgentsSearchResultBlock object
A block containing a web search result.
type: "search_result"
citations: BetaManagedAgentsSearchResultCitations
Citation settings for this search result.
enabled: boolean
Whether citations are enabled for this search result.
content: array of BetaManagedAgentsSearchResultContent
Array of text content blocks from the search result.
type: "text"
text: string
The text content.
minLength: 1
source: string
The URL source of the search result.
minLength: 1
title: string
The title of the search result.
minLength: 1
is_error: optional boolean or null
Whether the tool execution resulted in an error.
processed_at: optional string or null
Timestamp when this result was processed.
format: date-time
session_thread_id: optional string or null
Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread.
Sessions › Events
List Events
GET /v1/sessions/{session_id}/events
List Events
Path parameters
session_id: string
Query parameters
"created_at[gt]": optional string
Return events created after this time (exclusive). Compared against the event's processed_at value.
format: date-time
"created_at[gte]": optional string
Return events created at or after this time (inclusive). Compared against the event's processed_at value.
format: date-time
"created_at[lt]": optional string
Return events created before this time (exclusive). Compared against the event's processed_at value.
format: date-time
"created_at[lte]": optional string
Return events created at or before this time (inclusive). Compared against the event's processed_at value.
format: date-time
limit: optional number
format: int32
order: optional "asc" or "desc"
Sort direction for results, ordered by the event's processed_at. Defaults to asc (chronological).
"asc"
"desc"
page: optional string
Opaque pagination cursor from a previous response's next_page.
types: optional array of string
Filter by event type. Values match the type field on returned events (for example, user.message or agent.tool_use). Omit to return all event types.
Headers
"juglow-beta": optional array of JuglowBeta
Optional header to specify the beta version(s) you want to use.
string
"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 45 more
"message-batches-2024-09-24"
"prompt-caching-2024-07-31"
"computer-use-2024-10-22"
"computer-use-2025-01-24"
"pdfs-2024-09-25"
"token-counting-2024-11-01"
"token-efficient-tools-2025-02-19"
"output-128k-2025-02-19"
"files-api-2025-04-14"
"mcp-client-2025-04-04"
"mcp-client-2025-11-20"
"dev-full-thinking-2025-05-14"
"interleaved-thinking-2025-05-14"
"code-execution-2025-05-22"
"extended-cache-ttl-2025-04-11"
"context-1m-2025-08-07"
"context-management-2025-06-27"
"model-context-window-exceeded-2025-08-26"
"tracks-2025-10-02"
"fast-mode-2026-02-01"
"output-300k-2026-03-24"
"user-profiles-2026-03-24"
"user-profiles-2026-08-18"
"user-profiles-2026-09-04"
"advisor-tool-2026-03-01"
"managed-agents-2026-04-01"
"cache-diagnosis-2026-04-07"
"dreaming-2026-04-21"
"thinking-token-count-2026-05-13"
"server-side-fallback-2026-06-01"
"server-side-fallback-2026-07-01"
"fallback-credit-2026-06-01"
"fallback-credit-2026-07-01"
"agent-memory-2026-07-22"
"mid-conversation-tool-changes-2026-07-01"
"compact-2026-01-12"
"computer-use-2025-11-24"
"mcp-tunnels-2026-06-22"
"structured-outputs-2025-11-13"
"task-budgets-2026-03-13"
"thinking-display-updates-2026-08-18"
"ce-user-management-2026-07-13"
"mid-conversation-output-config-2026-07-01"
"thinking-binding-controls-2026-08-01"
"mid-conversation-system-clear-at-2026-08-21"
"compact-2026-09-04"
"inline-tools-2026-09-15"
"mcp-client-2026-09-15"
"juglow-workspace-id": optional string
Optional header to select the Workspace for this request. The value is a Workspace ID (for example, wrkspc_011CZkZaBF1tNoB5wlCeusgy).
Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.
Returns
data: optional array of BetaManagedAgentsSessionEvent
Events for the session, ordered by processed_at.
BetaManagedAgentsUserMessageEvent object
A user message event in the session conversation.
type: "user.message"
id: string
Unique identifier for this event.
content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock
Array of content blocks comprising the user message.
BetaManagedAgentsTextBlock object
Regular text content.
type: "text"
text: string
The text content.
minLength: 1
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
type: "image"
source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource
The source of the image data.
BetaManagedAgentsBase64ImageSource object
Base64-encoded image data.
type: "base64"
data: string
Base64-encoded image data.
minLength: 1
media_type: string
MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
minLength: 1
BetaManagedAgentsURLImageSource object
Image referenced by URL.
type: "url"
url: string
URL of the image to fetch.
minLength: 1
BetaManagedAgentsFileImageSource object
Image referenced by file ID.
type: "file"
file_id: string
ID of a previously uploaded file.
minLength: 1
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
type: "document"
source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource
The source of the document data.
BetaManagedAgentsBase64DocumentSource object
Base64-encoded document data.
type: "base64"
data: string
Base64-encoded document data.
minLength: 1
media_type: string
MIME type of the document (e.g., "application/pdf").
minLength: 1
BetaManagedAgentsPlainTextDocumentSource object
Plain text document content.
type: "text"
data: string
The plain text content.
minLength: 1
media_type: "text/plain"
MIME type of the text content. Must be "text/plain".
BetaManagedAgentsURLDocumentSource object
Document referenced by URL.
type: "url"
url: string
URL of the document to fetch.
minLength: 1
BetaManagedAgentsFileDocumentSource object
Document referenced by file ID.
type: "file"
file_id: string
ID of a previously uploaded file.
minLength: 1
context: optional string or null
Additional context about the document for the model.
title: optional string or null
The title of the document.
BetaManagedAgentsRedactedBlock object
Placeholder for content withheld by Juglow model policy.
type: "redacted"
processed_at: optional string or null
Timestamp when the agent finished processing this message.
format: date-time
BetaManagedAgentsUserInterruptEvent object
An interrupt event that pauses agent execution and returns control to the user.
type: "user.interrupt"
id: string
Unique identifier for this event.
processed_at: optional string or null
Timestamp when the interrupt was processed.
format: date-time
session_thread_id: optional string or null
If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.
BetaManagedAgentsUserToolConfirmationEvent object
A tool confirmation event that approves or denies a pending tool execution.
type: "user.tool_confirmation"
id: string
Unique identifier for this event.
result: "allow" or "deny"
The confirmation result: 'allow' or 'deny'.
"allow"
"deny"
tool_use_id: string
The id of the agent.tool_use or agent.mcp_tool_use event this result corresponds to, which can be found in the last session.status_idle event's stop_reason.event_ids field.
deny_message: optional string or null
Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
maxLength: 10000
processed_at: optional string or null
Timestamp when the confirmation was processed.
format: date-time
session_thread_id: optional string or null
Set by the server to the subagent thread this confirmation was routed to. Omitted when it was routed to the primary thread.
BetaManagedAgentsUserCustomToolResultEvent object
Event sent by the client providing the result of a custom tool execution.
type: "user.custom_tool_result"
id: string
Unique identifier for this event.
custom_tool_use_id: string
The id of the agent.custom_tool_use event this result corresponds to, which can be found in the last session.status_idle event's stop_reason.event_ids field.
content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock
The result content returned by the tool.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
BetaManagedAgentsSearchResultBlock object
A block containing a web search result.
type: "search_result"
citations: BetaManagedAgentsSearchResultCitations
Citation settings for this search result.
enabled: boolean
Whether citations are enabled for this search result.
content: array of BetaManagedAgentsSearchResultContent
Array of text content blocks from the search result.
type: "text"
text: string
The text content.
minLength: 1
source: string
The URL source of the search result.
minLength: 1
title: string
The title of the search result.
minLength: 1
is_error: optional boolean or null
Whether the tool execution resulted in an error.
processed_at: optional string or null
Timestamp when this result was processed.
format: date-time
session_thread_id: optional string or null
Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread.
BetaManagedAgentsAgentCustomToolUseEvent object
Event emitted when the agent calls a custom tool. The session goes idle until the client sends a user.custom_tool_result event with the result.
type: "agent.custom_tool_use"
id: string
Unique identifier for this event.
input: map[unknown]
Input parameters for the tool call.
name: string
Name of the custom tool being called.
processed_at: string
Timestamp when this tool use was processed.
format: date-time
session_thread_id: optional string or null
When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching user.custom_tool_result by custom_tool_use_id, so clients do not send it back.
BetaManagedAgentsAgentMessageEvent object
An agent response event in the session conversation.
type: "agent.message"
id: string
Unique identifier for this event.
content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsRedactedBlock
Array of text blocks comprising the agent response.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsRedactedBlock object
Placeholder for content withheld by Juglow model policy.
processed_at: string
Timestamp when this response was generated.
format: date-time
BetaManagedAgentsAgentThinkingEvent object
Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.
type: "agent.thinking"
id: string
Unique identifier for this event.
processed_at: string
Timestamp when this thinking was produced.
format: date-time
BetaManagedAgentsAgentMCPToolUseEvent object
Event emitted when the agent invokes a tool provided by an MCP server.
type: "agent.mcp_tool_use"
id: string
Unique identifier for this event.
input: map[unknown]
Input parameters for the tool call.
mcp_server_name: string
Name of the MCP server providing the tool.
name: string
Name of the MCP tool being used.
processed_at: string
Timestamp when this event was processed.
format: date-time
evaluated_permission: optional BetaManagedAgentsAgentEvaluatedPermission
The evaluated permission policy for this tool invocation.
"allow"
"ask"
"deny"
evaluation: optional BetaManagedAgentsAgentToolEvaluation
Which resolved permission_policy produced evaluated_permission: always_allow, always_ask, or auto (with the server's per-invocation judgement). Absent only when the server refused the call before any policy applied (for example, the named tool is not enabled in the session); such a refusal has evaluated_permission deny. An event recorded before this field existed reads as the arm its evaluated_permission implies (always_allow for allow, always_ask for ask).
BetaManagedAgentsAgentToolEvaluationAlwaysAllow object
The resolved permission_policy was always_allow; accompanies evaluated_permission "allow".
type: "always_allow"
BetaManagedAgentsAgentToolEvaluationAlwaysAsk object
The resolved permission_policy was always_ask; accompanies evaluated_permission "ask".
type: "always_ask"
BetaManagedAgentsAgentToolEvaluationAuto object
The resolved permission_policy was auto: the server judged this invocation individually.
type: "auto"
evaluated_permission: BetaManagedAgentsAgentAutoEvaluatedPermission
The server's judgement for this invocation.
BetaManagedAgentsAgentAutoEvaluatedPermissionAllow object
The server judged the invocation safe to execute without client approval.
type: "allow"
BetaManagedAgentsAgentAutoEvaluatedPermissionAsk object
The server reached no judgement; the invocation is held for client approval.
type: "ask"
reason_code: string
The judgement's grounds in registry-bound terms, for client branching and audit rather than end-user display. Open registry; currently "indeterminate" (no judgement was reached). Clients must tolerate values outside this set.
maxLength: 64
BetaManagedAgentsAgentAutoEvaluatedPermissionDeny object
The server judged the invocation high-risk; it does not execute and a synthetic error tool result is appended.
type: "deny"
reason_code: string
The judgement's grounds in registry-bound terms. Open registry; currently "high_risk" (judged high-risk; the call does not run). Clients must tolerate values outside this set.
maxLength: 64
session_thread_id: optional string or null
When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching user.tool_confirmation by tool_use_id, so clients do not send it back.
BetaManagedAgentsAgentMCPToolResultEvent object
Event representing the result of an MCP tool execution.
type: "agent.mcp_tool_result"
id: string
Unique identifier for this event.
mcp_tool_use_id: string
The id of the agent.mcp_tool_use event this result corresponds to.
processed_at: string
Timestamp when this event was processed.
format: date-time
content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock
The result content returned by the tool.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
BetaManagedAgentsSearchResultBlock object
A block containing a web search result.
is_error: optional boolean or null
Whether the tool execution resulted in an error.
BetaManagedAgentsAgentToolUseEvent object
Event emitted when the agent invokes a built-in agent tool.
type: "agent.tool_use"
id: string
Unique identifier for this event.
input: map[unknown]
Input parameters for the tool call.
name: string
Name of the agent tool being used.
processed_at: string
Timestamp when this event was processed.
format: date-time
evaluated_permission: optional BetaManagedAgentsAgentEvaluatedPermission
The evaluated permission policy for this tool invocation.
evaluation: optional BetaManagedAgentsAgentToolEvaluation
Which resolved permission_policy produced evaluated_permission: always_allow, always_ask, or auto (with the server's per-invocation judgement). Absent only when the server refused the call before any policy applied (for example, the named tool is not enabled in the session); such a refusal has evaluated_permission deny. An event recorded before this field existed reads as the arm its evaluated_permission implies (always_allow for allow, always_ask for ask).
session_thread_id: optional string or null
When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching user.tool_confirmation or user.tool_result by tool_use_id, so clients do not send it back.
BetaManagedAgentsAgentToolResultEvent object
Event representing the result of an agent tool execution.
type: "agent.tool_result"
id: string
Unique identifier for this event.
processed_at: string
Timestamp when this event was processed.
format: date-time
tool_use_id: string
The id of the agent.tool_use event this result corresponds to.
content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock
The result content returned by the tool.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
BetaManagedAgentsSearchResultBlock object
A block containing a web search result.
is_error: optional boolean or null
Whether the tool execution resulted in an error.
BetaManagedAgentsAgentThreadMessageReceivedEvent object
Delivery event written to the target thread's input stream when an agent-to-agent message arrives.
type: "agent.thread_message_received"
id: string
Unique identifier for this event.
content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock
Message content blocks.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
BetaManagedAgentsRedactedBlock object
Placeholder for content withheld by Juglow model policy.
from_session_thread_id: string
Public sthr_ ID of the thread that sent the message.
processed_at: string
Timestamp when the message was received.
format: date-time
from_agent_name: optional string or null
Name of the callable agent this message came from. Absent when received from the primary agent.
BetaManagedAgentsAgentThreadMessageSentEvent object
Observability event emitted to the sender's output stream when an agent-to-agent message is sent.
type: "agent.thread_message_sent"
id: string
Unique identifier for this event.
content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock
Message content blocks.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
BetaManagedAgentsRedactedBlock object
Placeholder for content withheld by Juglow model policy.
processed_at: string
Timestamp when the message was sent.
format: date-time
to_session_thread_id: string
Public sthr_ ID of the thread the message was sent to.
to_agent_name: optional string or null
Name of the callable agent this message was sent to. Absent when sent to the primary agent.
BetaManagedAgentsAgentThreadContextCompactedEvent object
Indicates that context compaction (summarization) occurred during the session.
type: "agent.thread_context_compacted"
id: string
Unique identifier for this event.
processed_at: string
Timestamp when compaction was processed.
format: date-time
BetaManagedAgentsSessionErrorEvent object
An error event indicating a problem occurred during session execution.
type: "session.error"
id: string
Unique identifier for this event.
error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 5 more
BetaManagedAgentsUnknownError object
An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on retry_status and message alone.
type: "unknown_error"
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
type: "retrying"
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
type: "exhausted"
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
type: "terminal"
BetaManagedAgentsModelOverloadedError object
The model is currently overloaded. Emitted after automatic retries are exhausted.
type: "model_overloaded_error"
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
BetaManagedAgentsModelRateLimitedError object
The model request was rate-limited.
type: "model_rate_limited_error"
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
BetaManagedAgentsModelRequestFailedError object
A model request failed for a reason other than overload or rate-limiting.
type: "model_request_failed_error"
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
BetaManagedAgentsMCPConnectionFailedError object
Failed to connect to an MCP server.
type: "mcp_connection_failed_error"
mcp_server_name: string
Name of the MCP server that failed to connect.
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
BetaManagedAgentsMCPAuthenticationFailedError object
Authentication to an MCP server failed.
type: "mcp_authentication_failed_error"
mcp_server_name: string
Name of the MCP server that failed authentication.
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
BetaManagedAgentsBillingError object
The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state.
type: "billing_error"
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
BetaManagedAgentsCredentialHostUnreachableError object
An environment_variable credential's auth.networking.allowed_hosts includes a host the environment's network policy does not permit.
type: "credential_host_unreachable_error"
credential_id: string
ID of the affected credential.
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
vault_id: string
ID of the vault containing the affected credential.
processed_at: string
Timestamp when the error occurred.
format: date-time
BetaManagedAgentsSessionStatusRescheduledEvent object
Indicates the session is recovering from an error state and is rescheduled for execution.
type: "session.status_rescheduled"
id: string
Unique identifier for this event.
processed_at: string
Timestamp of status change.
format: date-time
BetaManagedAgentsSessionStatusRunningEvent object
Indicates the session is actively running and the agent is working.
type: "session.status_running"
id: string
Unique identifier for this event.
processed_at: string
Timestamp of status change.
format: date-time
BetaManagedAgentsSessionStatusIdleEvent object
Indicates the agent has paused and is awaiting user input.
type: "session.status_idle"
id: string
Unique identifier for this event.
processed_at: string
Timestamp of status change.
format: date-time
stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached
BetaManagedAgentsSessionEndTurn object
The agent completed its turn naturally and is ready for the next user message.
type: "end_turn"
BetaManagedAgentsSessionRequiresAction object
The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.
type: "requires_action"
event_ids: array of string
The ids of events the agent is blocked on. Resolving fewer than all re-emits session.status_idle with the remainder.
BetaManagedAgentsSessionRetriesExhausted object
The turn ended because repeated errors exhausted the retry budget or an error escalated to retry_status: 'exhausted'.
type: "retries_exhausted"
BetaManagedAgentsSessionBudgetReached object
The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget.
type: "budget_reached"
BetaManagedAgentsSessionStatusTerminatedEvent object
Indicates the session has terminated, either due to an error or completion.
type: "session.status_terminated"
id: string
Unique identifier for this event.
processed_at: string
Timestamp of status change.
format: date-time
BetaManagedAgentsSessionThreadCreatedEvent object
Emitted when a subagent is spawned as a new thread. Written to the parent thread's output stream so clients observing the session see child creation.
type: "session.thread_created"
id: string
Unique identifier for this event.
agent_name: string
Name of the callable agent the thread runs.
processed_at: string
Timestamp when the thread was created.
format: date-time
session_thread_id: string
Public sthr_ ID of the newly created thread.
BetaManagedAgentsSpanOutcomeEvaluationStartEvent object
Emitted when an outcome evaluation cycle begins.
type: "span.outcome_evaluation_start"
id: string
Unique identifier for this event.
iteration: number
0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.
format: int32
outcome_id: string
The outc_ ID of the outcome being evaluated.
processed_at: string
Timestamp when outcome evaluation started.
format: date-time
BetaManagedAgentsSpanOutcomeEvaluationEndEvent object
Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of needs_revision means another evaluation cycle follows; satisfied, max_iterations_reached, failed, or interrupted are terminal — no further evaluation cycles follow.
type: "span.outcome_evaluation_end"
id: string
Unique identifier for this event.
explanation: string
Human-readable explanation of the verdict. For needs_revision, describes which criteria failed and why.
iteration: number
0-indexed revision cycle, matching the corresponding span.outcome_evaluation_start.
format: int32
outcome_evaluation_start_id: string
The id of the corresponding span.outcome_evaluation_start event.
outcome_id: string
The outc_ ID of the outcome being evaluated.
processed_at: string
Timestamp when outcome evaluation ended.
format: date-time
result: string
Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress.
usage: BetaManagedAgentsSpanModelUsage
Aggregate token usage for this evaluation cycle. Sums across all grader model requests within the cycle.
cache_creation_input_tokens: number
Tokens used to create prompt cache in this request.
format: int32
cache_read_input_tokens: number
Tokens read from prompt cache in this request.
format: int32
input_tokens: number
Input tokens consumed by this request.
format: int32
output_tokens: number
Output tokens generated by this request.
format: int32
speed: optional "standard" or "fast" or null
Inference speed tier this request actually ran at. Mirrors usage.speed on /v1/messages. Only present when the fast-mode beta is active.
"standard"
"fast"
BetaManagedAgentsSpanModelRequestStartEvent object
Emitted when a model request is initiated by the agent.
type: "span.model_request_start"
id: string
Unique identifier for this event.
processed_at: string
Timestamp when the model request started.
format: date-time
BetaManagedAgentsSpanModelRequestEndEvent object
Emitted when a model request completes.
type: "span.model_request_end"
id: string
Unique identifier for this event.
is_error: boolean or null
Whether the model request resulted in an error.
model_request_start_id: string
The id of the corresponding span.model_request_start event.
model_usage: BetaManagedAgentsSpanModelUsage
Token usage for this model request.
processed_at: string
Timestamp when the model request completed.
format: date-time
BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object
Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding span.outcome_evaluation_start and span.outcome_evaluation_end events.
type: "span.outcome_evaluation_ongoing"
id: string
Unique identifier for this event.
iteration: number
0-indexed revision cycle, matching the corresponding span.outcome_evaluation_start.
format: int32
outcome_id: string
The outc_ ID of the outcome being evaluated.
processed_at: string
Timestamp when this heartbeat was emitted.
format: date-time
BetaManagedAgentsUserDefineOutcomeEvent object
Echo of a user.define_outcome input event. Carries the server-generated outcome_id that subsequent span.outcome_evaluation_* events reference.
type: "user.define_outcome"
id: string
Unique identifier for this event.
description: string
What the agent should produce. Copied from the input event.
max_iterations: number or null
Evaluate-then-revise cycles before giving up. Default 3, max 20.
format: int32
outcome_id: string
Server-generated outc_ ID for this outcome. Referenced by span.outcome_evaluation_* events and the session's outcome_evaluations list.
processed_at: string
Timestamp when the outcome was accepted.
format: date-time
rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric
How to grade the outcome. File rubrics are currently resolved to their text content; clients should handle both variants.
BetaManagedAgentsFileRubric object
Rubric referenced by a file uploaded via the Files API.
type: "file"
file_id: string
ID of the rubric file.
BetaManagedAgentsTextRubric object
Rubric content provided inline as text.
type: "text"
content: string
Rubric content. Plain text or markdown — the grader treats it as freeform text.
BetaManagedAgentsSessionDeletedEvent object
Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.
type: "session.deleted"
id: string
Unique identifier for this event.
processed_at: string
Timestamp when the session was deleted.
format: date-time
BetaManagedAgentsSessionThreadStatusRunningEvent object
A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
type: "session.thread_status_running"
id: string
Unique identifier for this event.
agent_name: string
Name of the agent the thread runs.
processed_at: string
Timestamp of the status transition.
format: date-time
session_thread_id: string
Public sthr_ ID of the thread that started running.
BetaManagedAgentsSessionThreadStatusIdleEvent object
A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
type: "session.thread_status_idle"
id: string
Unique identifier for this event.
agent_name: string
Name of the agent the thread runs.
processed_at: string
Timestamp of the status transition.
format: date-time
session_thread_id: string
Public sthr_ ID of the thread that went idle.
stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached
BetaManagedAgentsSessionEndTurn object
The agent completed its turn naturally and is ready for the next user message.
BetaManagedAgentsSessionRequiresAction object
The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.
BetaManagedAgentsSessionRetriesExhausted object
The turn ended because repeated errors exhausted the retry budget or an error escalated to retry_status: 'exhausted'.
BetaManagedAgentsSessionBudgetReached object
The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget.
BetaManagedAgentsSessionThreadStatusTerminatedEvent object
A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
type: "session.thread_status_terminated"
id: string
Unique identifier for this event.
agent_name: string
Name of the agent the thread runs.
processed_at: string
Timestamp of the status transition.
format: date-time
session_thread_id: string
Public sthr_ ID of the thread that terminated.
BetaManagedAgentsUserToolResultEvent object
Event sent by the client providing the result of an agent-toolset tool execution. Only valid on self_hosted environments, where sandbox-routed tools are executed by the client rather than the server.
type: "user.tool_result"
id: string
Unique identifier for this event.
tool_use_id: string
The id of the agent.tool_use event this result corresponds to, which can be found in the last session.status_idle event's stop_reason.event_ids field.
content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock
The result content returned by the tool.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
BetaManagedAgentsSearchResultBlock object
A block containing a web search result.
is_error: optional boolean or null
Whether the tool execution resulted in an error.
processed_at: optional string or null
Timestamp when this result was processed.
format: date-time
session_thread_id: optional string or null
Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread.
BetaManagedAgentsSessionThreadStatusRescheduledEvent object
A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
type: "session.thread_status_rescheduled"
id: string
Unique identifier for this event.
agent_name: string
Name of the agent the thread runs.
processed_at: string
Timestamp of the status transition.
format: date-time
session_thread_id: string
Public sthr_ ID of the thread that is retrying.
BetaManagedAgentsSessionUpdatedEvent object
Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn.
type: "session.updated"
id: string
Unique identifier for this event.
processed_at: string
Timestamp when the update was applied.
format: date-time
agent: optional BetaManagedAgentsSessionAgent or null
The session's effective agent configuration after the update. Present only when the update changed agent (tools or mcp_servers); when present it is the full materialised snapshot, not a diff.
type: "agent"
id: string
description: string or null
mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition
type: "url"
name: string
url: string
model: BetaManagedAgentsModelConfig
Model identifier and configuration.
id: BetaManagedAgentsModel
The model that will power your agent.
See models for additional details and options.
string
"haijun-opus-5-5" or "haijun-fable-5-1" or "haijun-sonnet-5" or 12 more
The model that will power your agent.
See models for additional details and options.
"haijun-opus-5-5"
Powerful intelligence for coding, knowledge work, and long-running agents
"haijun-fable-5-1"
Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
"haijun-sonnet-5"
High-performance model for coding and agents
"haijun-fable-5"
Next generation of intelligence for the hardest knowledge work and coding problems
"haijun-opus-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-8"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-7"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-6"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-6"
Best combination of speed and intelligence
"haijun-haiku-4-5"
Fastest model with near-frontier intelligence
"haijun-haiku-4-5-20251001"
Fastest model with near-frontier intelligence
"haijun-opus-4-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-5-20251101"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-5"
High-performance model for agents and coding
"haijun-sonnet-4-5-20250929"
High-performance model for agents and coding
effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
How hard Haijun works on each inference call. One of low, medium, high, xhigh, max. Always present; resolved to the per-model default at save time when not supplied.
BetaManagedAgentsEffortLow object
Low effort. Favors latency over reasoning depth.
type: "low"
BetaManagedAgentsEffortMedium object
Medium effort. Balances latency and reasoning depth.
type: "medium"
BetaManagedAgentsEffortHigh object
High effort. Favors reasoning depth.
type: "high"
BetaManagedAgentsEffortXhigh object
Extra-high effort. Not all models accept this level.
type: "xhigh"
BetaManagedAgentsEffortMax object
Maximum effort. Favors reasoning depth over latency.
type: "max"
inference_geo: optional string
Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
speed: optional "standard" or "fast"
Inference speed mode. fast provides significantly faster output token generation at premium pricing. Defaults to standard. Not all models support fast; invalid combinations are rejected at create time.
"standard"
"fast"
multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null
Resolved multiagent orchestration configuration. Null when the agent is single-threaded.
type: "coordinator"
agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor
Full agent definitions the coordinator may spawn as session threads.
BetaManagedAgentsSessionThreadAgent object
Resolved agent definition for a single session_thread. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from Session.agent.
type: "agent"
id: string
description: string or null
mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition
type: "url"
name: string
url: string
model: BetaManagedAgentsModelConfig
Model identifier and configuration.
name: string
tracks: array of BetaManagedAgentsJuglowSkill or BetaManagedAgentsCustomSkill
BetaManagedAgentsJuglowSkill object
A resolved Juglow-managed track.
type: "juglow"
skill_id: string
version: string
BetaManagedAgentsCustomSkill object
A resolved user-created custom track.
type: "custom"
skill_id: string
version: string
system: string or null
tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool
BetaManagedAgentsAgentToolset20260401 object
type: "agent_toolset_20260401"
configs: array of BetaManagedAgentsAgentToolConfig
BetaManagedAgentsBashToolConfig object
Configuration for the bash tool.
type: "bash"
enabled: boolean
name: "bash"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
type: "always_allow"
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
type: "always_ask"
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
type: "auto"
BetaManagedAgentsEditToolConfig object
Configuration for the edit tool.
type: "edit"
enabled: boolean
name: "edit"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsReadToolConfig object
Configuration for the read tool.
type: "read"
enabled: boolean
name: "read"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWriteToolConfig object
Configuration for the write tool.
type: "write"
enabled: boolean
name: "write"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGlobToolConfig object
Configuration for the glob tool.
type: "glob"
enabled: boolean
name: "glob"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGrepToolConfig object
Configuration for the grep tool.
type: "grep"
enabled: boolean
name: "grep"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWebFetchToolConfig object
Configuration for the web_fetch tool.
type: "web_fetch"
enabled: boolean
name: "web_fetch"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
max_content_tokens: optional number or null
format: int32
BetaManagedAgentsWebSearchToolConfig object
Configuration for the web_search tool.
type: "web_search"
enabled: boolean
name: "web_search"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
user_location: optional BetaManagedAgentsUserLocation or null
Approximate user location for search result localization.
type: "approximate"
Location precision. Only "approximate" is supported.
city: optional string or null
City name.
minLength: 1, maxLength: 255
country: optional string or null
Two-letter ISO 3166-1 country code, uppercase.
region: optional string or null
Region or state name.
minLength: 1, maxLength: 255
timezone: optional string or null
IANA timezone identifier, e.g. "America/Los_Angeles".
minLength: 1, maxLength: 255
default_config: BetaManagedAgentsAgentToolsetDefaultConfig
Resolved default configuration for agent tools.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsMCPToolset object
type: "mcp_toolset"
configs: array of BetaManagedAgentsMCPToolConfig
enabled: boolean
name: string
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
default_config: BetaManagedAgentsMCPToolsetDefaultConfig
Resolved default configuration for all tools from an MCP server.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
mcp_server_name: string
BetaManagedAgentsCustomTool object
A custom tool as returned in API responses.
type: "custom"
description: string
input_schema: BetaManagedAgentsCustomToolInputSchema
JSON Schema for custom tool input parameters.
type: "object"
properties: optional map[unknown] or null
required: optional array of string or null
name: string
version: number
format: int32
BetaManagedAgentsAdvisor object
Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
type: "advisor"
model: string
The advisor model id.
name: string
tracks: array of BetaManagedAgentsJuglowSkill or BetaManagedAgentsCustomSkill
BetaManagedAgentsJuglowSkill object
A resolved Juglow-managed track.
BetaManagedAgentsCustomSkill object
A resolved user-created custom track.
system: string or null
tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool
BetaManagedAgentsAgentToolset20260401 object
BetaManagedAgentsMCPToolset object
BetaManagedAgentsCustomTool object
A custom tool as returned in API responses.
version: number
format: int32
budget: optional BetaManagedAgentsBudgetLimit or null
The session's budget after the update: the new budget when set or replaced, or null when the update removed it. Present only when the update changed the budget.
type: "limit"
max_list_cost: BetaMonetaryAmount
Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge.
amount: string
Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.
currency: BetaCurrency
Uppercase ISO-4217 currency code. USD is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.
metadata: optional map[string]
The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty.
title: optional string or null
The session's new title. Present only when the update changed it.
BetaManagedAgentsSystemMessageEvent object
A mid-conversation system message event. Carries system-role content that is appended to the session as a role: "system" turn.
type: "system.message"
id: string
Unique identifier for this event.
content: array of BetaManagedAgentsSystemContentBlock
System content blocks. Text-only.
type: "text"
text: string
The text content.
minLength: 1
processed_at: optional string or null
Timestamp when this system message was processed.
format: date-time
BetaManagedAgentsSessionUsageEvent object
Periodic snapshot of the session's cumulative usage and tracked list cost.
type: "session.usage"
id: string
Unique identifier for this event.
processed_at: string
Timestamp when the snapshot was taken.
format: date-time
usage: BetaManagedAgentsSessionUsageSnapshot
The session's cumulative usage at the snapshot time.
active_seconds: optional number
Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once. This is the duration the session's runtime cost is priced on.
format: double
cache_creation: optional BetaManagedAgentsCacheCreationUsage
Tokens used to create prompt cache entries, broken down by cache TTL.
ephemeral_1h_input_tokens: optional number
Tokens used to create 1-hour ephemeral cache entries.
format: int32
ephemeral_5m_input_tokens: optional number
Tokens used to create 5-minute ephemeral cache entries.
format: int32
cache_read_input_tokens: optional number
Total tokens read from prompt cache.
format: int32
input_tokens: optional number
Total input tokens consumed across all turns.
format: int32
list_cost: optional BetaMonetaryAmount
Cumulative list cost of the session across all turns, priced at public list rates.
output_tokens: optional number
Total output tokens generated across all turns.
format: int32
server_tool_use: optional BetaManagedAgentsServerToolUsage
Cumulative server-executed tool usage across all turns.
web_fetch_requests: optional number
Number of server-executed web fetch requests.
format: int32
web_search_requests: optional number
Number of server-executed web search requests.
format: int32
budget: optional BetaManagedAgentsBudgetLimit or null
The session's configured budget at the snapshot time, or null when the session has no budget.
next_page: optional string or null
Opaque cursor for the next page. Null when no more results.
Example
curl https://haijun.my.id/v1/sessions/$SESSION_ID/events \
-H 'juglow-version: 2023-06-01' \
-H 'juglow-beta: managed-agents-2026-04-01' \
-H "X-Api-Key: $JUGLOW_API_KEY"Response (200)
{
"data": [
{
"id": "sevt_011CZkZGOp0iBcp4kaQSihUmy",
"content": [
{
"text": "Where is my order #1234?",
"type": "text"
}
],
"type": "user.message",
"processed_at": "2026-03-15T10:00:00Z"
},
{
"id": "sevt_011CZkZHPq1jCdq5lbRTjiVnz",
"content": [
{
"text": "Let me look up order #1234 for you.",
"type": "text"
}
],
"processed_at": "2026-03-15T10:00:00Z",
"type": "agent.message"
}
],
"next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
}Send Events
POST /v1/sessions/{session_id}/events
Send Events
Path parameters
session_id: string
Headers
"juglow-beta": optional array of JuglowBeta
Optional header to specify the beta version(s) you want to use.
string
"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 45 more
"message-batches-2024-09-24"
"prompt-caching-2024-07-31"
"computer-use-2024-10-22"
"computer-use-2025-01-24"
"pdfs-2024-09-25"
"token-counting-2024-11-01"
"token-efficient-tools-2025-02-19"
"output-128k-2025-02-19"
"files-api-2025-04-14"
"mcp-client-2025-04-04"
"mcp-client-2025-11-20"
"dev-full-thinking-2025-05-14"
"interleaved-thinking-2025-05-14"
"code-execution-2025-05-22"
"extended-cache-ttl-2025-04-11"
"context-1m-2025-08-07"
"context-management-2025-06-27"
"model-context-window-exceeded-2025-08-26"
"tracks-2025-10-02"
"fast-mode-2026-02-01"
"output-300k-2026-03-24"
"user-profiles-2026-03-24"
"user-profiles-2026-08-18"
"user-profiles-2026-09-04"
"advisor-tool-2026-03-01"
"managed-agents-2026-04-01"
"cache-diagnosis-2026-04-07"
"dreaming-2026-04-21"
"thinking-token-count-2026-05-13"
"server-side-fallback-2026-06-01"
"server-side-fallback-2026-07-01"
"fallback-credit-2026-06-01"
"fallback-credit-2026-07-01"
"agent-memory-2026-07-22"
"mid-conversation-tool-changes-2026-07-01"
"compact-2026-01-12"
"computer-use-2025-11-24"
"mcp-tunnels-2026-06-22"
"structured-outputs-2025-11-13"
"task-budgets-2026-03-13"
"thinking-display-updates-2026-08-18"
"ce-user-management-2026-07-13"
"mid-conversation-output-config-2026-07-01"
"thinking-binding-controls-2026-08-01"
"mid-conversation-system-clear-at-2026-08-21"
"compact-2026-09-04"
"inline-tools-2026-09-15"
"mcp-client-2026-09-15"
"juglow-workspace-id": optional string
Optional header to select the Workspace for this request. The value is a Workspace ID (for example, wrkspc_011CZkZaBF1tNoB5wlCeusgy).
Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.
Body parameters
events: array of BetaManagedAgentsEventParams
Events to send to the session.
BetaManagedAgentsUserMessageEventParams object
Parameters for sending a user message to the session.
type: "user.message"
content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock
Array of content blocks for the user message.
BetaManagedAgentsTextBlock object
Regular text content.
type: "text"
text: string
The text content.
minLength: 1
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
type: "image"
source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource
The source of the image data.
BetaManagedAgentsBase64ImageSource object
Base64-encoded image data.
type: "base64"
data: string
Base64-encoded image data.
minLength: 1
media_type: string
MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
minLength: 1
BetaManagedAgentsURLImageSource object
Image referenced by URL.
type: "url"
url: string
URL of the image to fetch.
minLength: 1
BetaManagedAgentsFileImageSource object
Image referenced by file ID.
type: "file"
file_id: string
ID of a previously uploaded file.
minLength: 1
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
type: "document"
source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource
The source of the document data.
BetaManagedAgentsBase64DocumentSource object
Base64-encoded document data.
type: "base64"
data: string
Base64-encoded document data.
minLength: 1
media_type: string
MIME type of the document (e.g., "application/pdf").
minLength: 1
BetaManagedAgentsPlainTextDocumentSource object
Plain text document content.
type: "text"
data: string
The plain text content.
minLength: 1
media_type: "text/plain"
MIME type of the text content. Must be "text/plain".
BetaManagedAgentsURLDocumentSource object
Document referenced by URL.
type: "url"
url: string
URL of the document to fetch.
minLength: 1
BetaManagedAgentsFileDocumentSource object
Document referenced by file ID.
type: "file"
file_id: string
ID of a previously uploaded file.
minLength: 1
context: optional string or null
Additional context about the document for the model.
title: optional string or null
The title of the document.
BetaManagedAgentsRedactedBlock object
Placeholder for content withheld by Juglow model policy.
type: "redacted"
BetaManagedAgentsUserInterruptEventParams object
Parameters for sending an interrupt to pause the agent.
type: "user.interrupt"
session_thread_id: optional string or null
If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.
BetaManagedAgentsUserToolConfirmationEventParams object
Parameters for confirming or denying a tool execution request.
type: "user.tool_confirmation"
result: "allow" or "deny"
The confirmation result: 'allow' or 'deny'.
"allow"
"deny"
tool_use_id: string
The id of the agent.tool_use or agent.mcp_tool_use event this result corresponds to, which can be found in the last session.status_idle event's stop_reason.event_ids field.
minLength: 1, maxLength: 128
deny_message: optional string or null
Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
maxLength: 10000
BetaManagedAgentsUserCustomToolResultEventParams object
Parameters for providing the result of a custom tool execution.
type: "user.custom_tool_result"
custom_tool_use_id: string
The id of the agent.custom_tool_use event this result corresponds to, which can be found in the last session.status_idle event's stop_reason.event_ids field.
minLength: 1, maxLength: 128
content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock
The result content returned by the tool.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
BetaManagedAgentsSearchResultBlock object
A block containing a web search result.
type: "search_result"
citations: BetaManagedAgentsSearchResultCitations
Citation settings for this search result.
enabled: boolean
Whether citations are enabled for this search result.
content: array of BetaManagedAgentsSearchResultContent
Array of text content blocks from the search result.
type: "text"
text: string
The text content.
minLength: 1
source: string
The URL source of the search result.
minLength: 1
title: string
The title of the search result.
minLength: 1
is_error: optional boolean or null
Whether the tool execution resulted in an error.
BetaManagedAgentsUserDefineOutcomeEventParams object
Parameters for defining an outcome the agent should work toward. The agent begins work on receipt.
type: "user.define_outcome"
description: string
What the agent should produce. This is the task specification.
rubric: BetaManagedAgentsFileRubricParams or BetaManagedAgentsTextRubricParams
How to grade the outcome. Text or file reference.
BetaManagedAgentsFileRubricParams object
Rubric referenced by a file uploaded via the Files API.
type: "file"
file_id: string
ID of the rubric file.
BetaManagedAgentsTextRubricParams object
Rubric content provided inline as text.
type: "text"
content: string
Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.
maxLength: 262144
max_iterations: optional number or null
Eval→revision cycles before giving up. Default 3, max 20.
format: int32
BetaManagedAgentsUserToolResultEventParams object
Parameters for providing the result of an agent-toolset tool execution. Only valid on self_hosted environments, where sandbox-routed tools are executed by the client rather than the server.
type: "user.tool_result"
tool_use_id: string
The id of the agent.tool_use event this result corresponds to, which can be found in the last session.status_idle event's stop_reason.event_ids field.
minLength: 1, maxLength: 128
content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock
The result content returned by the tool.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
BetaManagedAgentsSearchResultBlock object
A block containing a web search result.
is_error: optional boolean or null
Whether the tool execution resulted in an error.
BetaManagedAgentsSystemMessageEventParams object
Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a role: "system" turn rather than replacing the top-level system prompt. At most one per request: it must be the final event and immediately follow the user.message, user.tool_result, or user.custom_tool_result it accompanies. Only supported on models that accept mid-conversation system messages.
type: "system.message"
content: array of BetaManagedAgentsSystemContentBlock
System content blocks to append. Text-only.
type: "text"
text: string
The text content.
minLength: 1
Returns
BetaManagedAgentsSendSessionEvents object
Events that were successfully sent to the session.
data: optional array of BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 4 more
Sent events
BetaManagedAgentsUserMessageEvent object
A user message event in the session conversation.
type: "user.message"
id: string
Unique identifier for this event.
content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock
Array of content blocks comprising the user message.
BetaManagedAgentsTextBlock object
Regular text content.
type: "text"
text: string
The text content.
minLength: 1
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
type: "image"
source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource
The source of the image data.
BetaManagedAgentsBase64ImageSource object
Base64-encoded image data.
type: "base64"
data: string
Base64-encoded image data.
minLength: 1
media_type: string
MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
minLength: 1
BetaManagedAgentsURLImageSource object
Image referenced by URL.
type: "url"
url: string
URL of the image to fetch.
minLength: 1
BetaManagedAgentsFileImageSource object
Image referenced by file ID.
type: "file"
file_id: string
ID of a previously uploaded file.
minLength: 1
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
type: "document"
source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource
The source of the document data.
BetaManagedAgentsBase64DocumentSource object
Base64-encoded document data.
type: "base64"
data: string
Base64-encoded document data.
minLength: 1
media_type: string
MIME type of the document (e.g., "application/pdf").
minLength: 1
BetaManagedAgentsPlainTextDocumentSource object
Plain text document content.
type: "text"
data: string
The plain text content.
minLength: 1
media_type: "text/plain"
MIME type of the text content. Must be "text/plain".
BetaManagedAgentsURLDocumentSource object
Document referenced by URL.
type: "url"
url: string
URL of the document to fetch.
minLength: 1
BetaManagedAgentsFileDocumentSource object
Document referenced by file ID.
type: "file"
file_id: string
ID of a previously uploaded file.
minLength: 1
context: optional string or null
Additional context about the document for the model.
title: optional string or null
The title of the document.
BetaManagedAgentsRedactedBlock object
Placeholder for content withheld by Juglow model policy.
type: "redacted"
processed_at: optional string or null
Timestamp when the agent finished processing this message.
format: date-time
BetaManagedAgentsUserInterruptEvent object
An interrupt event that pauses agent execution and returns control to the user.
type: "user.interrupt"
id: string
Unique identifier for this event.
processed_at: optional string or null
Timestamp when the interrupt was processed.
format: date-time
session_thread_id: optional string or null
If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.
BetaManagedAgentsUserToolConfirmationEvent object
A tool confirmation event that approves or denies a pending tool execution.
type: "user.tool_confirmation"
id: string
Unique identifier for this event.
result: "allow" or "deny"
The confirmation result: 'allow' or 'deny'.
"allow"
"deny"
tool_use_id: string
The id of the agent.tool_use or agent.mcp_tool_use event this result corresponds to, which can be found in the last session.status_idle event's stop_reason.event_ids field.
deny_message: optional string or null
Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
maxLength: 10000
processed_at: optional string or null
Timestamp when the confirmation was processed.
format: date-time
session_thread_id: optional string or null
Set by the server to the subagent thread this confirmation was routed to. Omitted when it was routed to the primary thread.
BetaManagedAgentsUserCustomToolResultEvent object
Event sent by the client providing the result of a custom tool execution.
type: "user.custom_tool_result"
id: string
Unique identifier for this event.
custom_tool_use_id: string
The id of the agent.custom_tool_use event this result corresponds to, which can be found in the last session.status_idle event's stop_reason.event_ids field.
content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock
The result content returned by the tool.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
BetaManagedAgentsSearchResultBlock object
A block containing a web search result.
type: "search_result"
citations: BetaManagedAgentsSearchResultCitations
Citation settings for this search result.
enabled: boolean
Whether citations are enabled for this search result.
content: array of BetaManagedAgentsSearchResultContent
Array of text content blocks from the search result.
type: "text"
text: string
The text content.
minLength: 1
source: string
The URL source of the search result.
minLength: 1
title: string
The title of the search result.
minLength: 1
is_error: optional boolean or null
Whether the tool execution resulted in an error.
processed_at: optional string or null
Timestamp when this result was processed.
format: date-time
session_thread_id: optional string or null
Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread.
BetaManagedAgentsUserDefineOutcomeEvent object
Echo of a user.define_outcome input event. Carries the server-generated outcome_id that subsequent span.outcome_evaluation_* events reference.
type: "user.define_outcome"
id: string
Unique identifier for this event.
description: string
What the agent should produce. Copied from the input event.
max_iterations: number or null
Evaluate-then-revise cycles before giving up. Default 3, max 20.
format: int32
outcome_id: string
Server-generated outc_ ID for this outcome. Referenced by span.outcome_evaluation_* events and the session's outcome_evaluations list.
processed_at: string
Timestamp when the outcome was accepted.
format: date-time
rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric
How to grade the outcome. File rubrics are currently resolved to their text content; clients should handle both variants.
BetaManagedAgentsFileRubric object
Rubric referenced by a file uploaded via the Files API.
type: "file"
file_id: string
ID of the rubric file.
BetaManagedAgentsTextRubric object
Rubric content provided inline as text.
type: "text"
content: string
Rubric content. Plain text or markdown — the grader treats it as freeform text.
BetaManagedAgentsUserToolResultEvent object
Event sent by the client providing the result of an agent-toolset tool execution. Only valid on self_hosted environments, where sandbox-routed tools are executed by the client rather than the server.
type: "user.tool_result"
id: string
Unique identifier for this event.
tool_use_id: string
The id of the agent.tool_use event this result corresponds to, which can be found in the last session.status_idle event's stop_reason.event_ids field.
content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock
The result content returned by the tool.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
BetaManagedAgentsSearchResultBlock object
A block containing a web search result.
is_error: optional boolean or null
Whether the tool execution resulted in an error.
processed_at: optional string or null
Timestamp when this result was processed.
format: date-time
session_thread_id: optional string or null
Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread.
BetaManagedAgentsSystemMessageEvent object
A mid-conversation system message event. Carries system-role content that is appended to the session as a role: "system" turn.
type: "system.message"
id: string
Unique identifier for this event.
content: array of BetaManagedAgentsSystemContentBlock
System content blocks. Text-only.
type: "text"
text: string
The text content.
minLength: 1
processed_at: optional string or null
Timestamp when this system message was processed.
format: date-time
Example
curl https://haijun.my.id/v1/sessions/$SESSION_ID/events \
-H 'Content-Type: application/json' \
-H 'juglow-version: 2023-06-01' \
-H 'juglow-beta: managed-agents-2026-04-01' \
-H "X-Api-Key: $JUGLOW_API_KEY" \
-d '{
"events": [
{
"content": [
{
"text": "Where is my order #1234?",
"type": "text"
}
],
"type": "user.message"
}
]
}'Response (200)
{
"data": [
{
"id": "sevt_011CZkZGOp0iBcp4kaQSihUmy",
"content": [
{
"text": "Where is my order #1234?",
"type": "text"
}
],
"type": "user.message",
"processed_at": "2026-03-15T10:00:00Z"
}
]
}Stream Events
GET /v1/sessions/{session_id}/events/stream
Stream Events
Path parameters
session_id: string
Query parameters
event_deltas: optional array of BetaManagedAgentsDeltaType
When set, this connection also receives streaming deltas (event_start, event_delta) while an event is being produced, before the event itself arrives. Deltas are best-effort; when the final event is produced it carries the complete content. A model request that ends early (an error or interrupt) produces no final event — its terminal span.model_request_end closes the preview. Accepts one or more event types to preview and may be repeated: agent.message streams content_delta fragments; agent.thinking is start-only — a signal that the agent has begun extended thinking, concluded by the agent.thinking event itself. Only previews of the requested event types are sent.
"agent.message"
"agent.thinking"
Headers
"juglow-beta": optional array of JuglowBeta
Optional header to specify the beta version(s) you want to use.
string
"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 45 more
"message-batches-2024-09-24"
"prompt-caching-2024-07-31"
"computer-use-2024-10-22"
"computer-use-2025-01-24"
"pdfs-2024-09-25"
"token-counting-2024-11-01"
"token-efficient-tools-2025-02-19"
"output-128k-2025-02-19"
"files-api-2025-04-14"
"mcp-client-2025-04-04"
"mcp-client-2025-11-20"
"dev-full-thinking-2025-05-14"
"interleaved-thinking-2025-05-14"
"code-execution-2025-05-22"
"extended-cache-ttl-2025-04-11"
"context-1m-2025-08-07"
"context-management-2025-06-27"
"model-context-window-exceeded-2025-08-26"
"tracks-2025-10-02"
"fast-mode-2026-02-01"
"output-300k-2026-03-24"
"user-profiles-2026-03-24"
"user-profiles-2026-08-18"
"user-profiles-2026-09-04"
"advisor-tool-2026-03-01"
"managed-agents-2026-04-01"
"cache-diagnosis-2026-04-07"
"dreaming-2026-04-21"
"thinking-token-count-2026-05-13"
"server-side-fallback-2026-06-01"
"server-side-fallback-2026-07-01"
"fallback-credit-2026-06-01"
"fallback-credit-2026-07-01"
"agent-memory-2026-07-22"
"mid-conversation-tool-changes-2026-07-01"
"compact-2026-01-12"
"computer-use-2025-11-24"
"mcp-tunnels-2026-06-22"
"structured-outputs-2025-11-13"
"task-budgets-2026-03-13"
"thinking-display-updates-2026-08-18"
"ce-user-management-2026-07-13"
"mid-conversation-output-config-2026-07-01"
"thinking-binding-controls-2026-08-01"
"mid-conversation-system-clear-at-2026-08-21"
"compact-2026-09-04"
"inline-tools-2026-09-15"
"mcp-client-2026-09-15"
"juglow-workspace-id": optional string
Optional header to select the Workspace for this request. The value is a Workspace ID (for example, wrkspc_011CZkZaBF1tNoB5wlCeusgy).
Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.
Returns
BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 34 more
Server-sent event in the session stream.
BetaManagedAgentsUserMessageEvent object
A user message event in the session conversation.
type: "user.message"
id: string
Unique identifier for this event.
content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock
Array of content blocks comprising the user message.
BetaManagedAgentsTextBlock object
Regular text content.
type: "text"
text: string
The text content.
minLength: 1
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
type: "image"
source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource
The source of the image data.
BetaManagedAgentsBase64ImageSource object
Base64-encoded image data.
type: "base64"
data: string
Base64-encoded image data.
minLength: 1
media_type: string
MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
minLength: 1
BetaManagedAgentsURLImageSource object
Image referenced by URL.
type: "url"
url: string
URL of the image to fetch.
minLength: 1
BetaManagedAgentsFileImageSource object
Image referenced by file ID.
type: "file"
file_id: string
ID of a previously uploaded file.
minLength: 1
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
type: "document"
source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource
The source of the document data.
BetaManagedAgentsBase64DocumentSource object
Base64-encoded document data.
type: "base64"
data: string
Base64-encoded document data.
minLength: 1
media_type: string
MIME type of the document (e.g., "application/pdf").
minLength: 1
BetaManagedAgentsPlainTextDocumentSource object
Plain text document content.
type: "text"
data: string
The plain text content.
minLength: 1
media_type: "text/plain"
MIME type of the text content. Must be "text/plain".
BetaManagedAgentsURLDocumentSource object
Document referenced by URL.
type: "url"
url: string
URL of the document to fetch.
minLength: 1
BetaManagedAgentsFileDocumentSource object
Document referenced by file ID.
type: "file"
file_id: string
ID of a previously uploaded file.
minLength: 1
context: optional string or null
Additional context about the document for the model.
title: optional string or null
The title of the document.
BetaManagedAgentsRedactedBlock object
Placeholder for content withheld by Juglow model policy.
type: "redacted"
processed_at: optional string or null
Timestamp when the agent finished processing this message.
format: date-time
BetaManagedAgentsUserInterruptEvent object
An interrupt event that pauses agent execution and returns control to the user.
type: "user.interrupt"
id: string
Unique identifier for this event.
processed_at: optional string or null
Timestamp when the interrupt was processed.
format: date-time
session_thread_id: optional string or null
If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.
BetaManagedAgentsUserToolConfirmationEvent object
A tool confirmation event that approves or denies a pending tool execution.
type: "user.tool_confirmation"
id: string
Unique identifier for this event.
result: "allow" or "deny"
The confirmation result: 'allow' or 'deny'.
"allow"
"deny"
tool_use_id: string
The id of the agent.tool_use or agent.mcp_tool_use event this result corresponds to, which can be found in the last session.status_idle event's stop_reason.event_ids field.
deny_message: optional string or null
Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
maxLength: 10000
processed_at: optional string or null
Timestamp when the confirmation was processed.
format: date-time
session_thread_id: optional string or null
Set by the server to the subagent thread this confirmation was routed to. Omitted when it was routed to the primary thread.
BetaManagedAgentsUserCustomToolResultEvent object
Event sent by the client providing the result of a custom tool execution.
type: "user.custom_tool_result"
id: string
Unique identifier for this event.
custom_tool_use_id: string
The id of the agent.custom_tool_use event this result corresponds to, which can be found in the last session.status_idle event's stop_reason.event_ids field.
content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock
The result content returned by the tool.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
BetaManagedAgentsSearchResultBlock object
A block containing a web search result.
type: "search_result"
citations: BetaManagedAgentsSearchResultCitations
Citation settings for this search result.
enabled: boolean
Whether citations are enabled for this search result.
content: array of BetaManagedAgentsSearchResultContent
Array of text content blocks from the search result.
type: "text"
text: string
The text content.
minLength: 1
source: string
The URL source of the search result.
minLength: 1
title: string
The title of the search result.
minLength: 1
is_error: optional boolean or null
Whether the tool execution resulted in an error.
processed_at: optional string or null
Timestamp when this result was processed.
format: date-time
session_thread_id: optional string or null
Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread.
BetaManagedAgentsAgentCustomToolUseEvent object
Event emitted when the agent calls a custom tool. The session goes idle until the client sends a user.custom_tool_result event with the result.
type: "agent.custom_tool_use"
id: string
Unique identifier for this event.
input: map[unknown]
Input parameters for the tool call.
name: string
Name of the custom tool being called.
processed_at: string
Timestamp when this tool use was processed.
format: date-time
session_thread_id: optional string or null
When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching user.custom_tool_result by custom_tool_use_id, so clients do not send it back.
BetaManagedAgentsAgentMessageEvent object
An agent response event in the session conversation.
type: "agent.message"
id: string
Unique identifier for this event.
content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsRedactedBlock
Array of text blocks comprising the agent response.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsRedactedBlock object
Placeholder for content withheld by Juglow model policy.
processed_at: string
Timestamp when this response was generated.
format: date-time
BetaManagedAgentsAgentThinkingEvent object
Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.
type: "agent.thinking"
id: string
Unique identifier for this event.
processed_at: string
Timestamp when this thinking was produced.
format: date-time
BetaManagedAgentsAgentMCPToolUseEvent object
Event emitted when the agent invokes a tool provided by an MCP server.
type: "agent.mcp_tool_use"
id: string
Unique identifier for this event.
input: map[unknown]
Input parameters for the tool call.
mcp_server_name: string
Name of the MCP server providing the tool.
name: string
Name of the MCP tool being used.
processed_at: string
Timestamp when this event was processed.
format: date-time
evaluated_permission: optional BetaManagedAgentsAgentEvaluatedPermission
The evaluated permission policy for this tool invocation.
"allow"
"ask"
"deny"
evaluation: optional BetaManagedAgentsAgentToolEvaluation
Which resolved permission_policy produced evaluated_permission: always_allow, always_ask, or auto (with the server's per-invocation judgement). Absent only when the server refused the call before any policy applied (for example, the named tool is not enabled in the session); such a refusal has evaluated_permission deny. An event recorded before this field existed reads as the arm its evaluated_permission implies (always_allow for allow, always_ask for ask).
BetaManagedAgentsAgentToolEvaluationAlwaysAllow object
The resolved permission_policy was always_allow; accompanies evaluated_permission "allow".
type: "always_allow"
BetaManagedAgentsAgentToolEvaluationAlwaysAsk object
The resolved permission_policy was always_ask; accompanies evaluated_permission "ask".
type: "always_ask"
BetaManagedAgentsAgentToolEvaluationAuto object
The resolved permission_policy was auto: the server judged this invocation individually.
type: "auto"
evaluated_permission: BetaManagedAgentsAgentAutoEvaluatedPermission
The server's judgement for this invocation.
BetaManagedAgentsAgentAutoEvaluatedPermissionAllow object
The server judged the invocation safe to execute without client approval.
type: "allow"
BetaManagedAgentsAgentAutoEvaluatedPermissionAsk object
The server reached no judgement; the invocation is held for client approval.
type: "ask"
reason_code: string
The judgement's grounds in registry-bound terms, for client branching and audit rather than end-user display. Open registry; currently "indeterminate" (no judgement was reached). Clients must tolerate values outside this set.
maxLength: 64
BetaManagedAgentsAgentAutoEvaluatedPermissionDeny object
The server judged the invocation high-risk; it does not execute and a synthetic error tool result is appended.
type: "deny"
reason_code: string
The judgement's grounds in registry-bound terms. Open registry; currently "high_risk" (judged high-risk; the call does not run). Clients must tolerate values outside this set.
maxLength: 64
session_thread_id: optional string or null
When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching user.tool_confirmation by tool_use_id, so clients do not send it back.
BetaManagedAgentsAgentMCPToolResultEvent object
Event representing the result of an MCP tool execution.
type: "agent.mcp_tool_result"
id: string
Unique identifier for this event.
mcp_tool_use_id: string
The id of the agent.mcp_tool_use event this result corresponds to.
processed_at: string
Timestamp when this event was processed.
format: date-time
content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock
The result content returned by the tool.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
BetaManagedAgentsSearchResultBlock object
A block containing a web search result.
is_error: optional boolean or null
Whether the tool execution resulted in an error.
BetaManagedAgentsAgentToolUseEvent object
Event emitted when the agent invokes a built-in agent tool.
type: "agent.tool_use"
id: string
Unique identifier for this event.
input: map[unknown]
Input parameters for the tool call.
name: string
Name of the agent tool being used.
processed_at: string
Timestamp when this event was processed.
format: date-time
evaluated_permission: optional BetaManagedAgentsAgentEvaluatedPermission
The evaluated permission policy for this tool invocation.
evaluation: optional BetaManagedAgentsAgentToolEvaluation
Which resolved permission_policy produced evaluated_permission: always_allow, always_ask, or auto (with the server's per-invocation judgement). Absent only when the server refused the call before any policy applied (for example, the named tool is not enabled in the session); such a refusal has evaluated_permission deny. An event recorded before this field existed reads as the arm its evaluated_permission implies (always_allow for allow, always_ask for ask).
session_thread_id: optional string or null
When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching user.tool_confirmation or user.tool_result by tool_use_id, so clients do not send it back.
BetaManagedAgentsAgentToolResultEvent object
Event representing the result of an agent tool execution.
type: "agent.tool_result"
id: string
Unique identifier for this event.
processed_at: string
Timestamp when this event was processed.
format: date-time
tool_use_id: string
The id of the agent.tool_use event this result corresponds to.
content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock
The result content returned by the tool.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
BetaManagedAgentsSearchResultBlock object
A block containing a web search result.
is_error: optional boolean or null
Whether the tool execution resulted in an error.
BetaManagedAgentsAgentThreadMessageReceivedEvent object
Delivery event written to the target thread's input stream when an agent-to-agent message arrives.
type: "agent.thread_message_received"
id: string
Unique identifier for this event.
content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock
Message content blocks.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
BetaManagedAgentsRedactedBlock object
Placeholder for content withheld by Juglow model policy.
from_session_thread_id: string
Public sthr_ ID of the thread that sent the message.
processed_at: string
Timestamp when the message was received.
format: date-time
from_agent_name: optional string or null
Name of the callable agent this message came from. Absent when received from the primary agent.
BetaManagedAgentsAgentThreadMessageSentEvent object
Observability event emitted to the sender's output stream when an agent-to-agent message is sent.
type: "agent.thread_message_sent"
id: string
Unique identifier for this event.
content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock
Message content blocks.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
BetaManagedAgentsRedactedBlock object
Placeholder for content withheld by Juglow model policy.
processed_at: string
Timestamp when the message was sent.
format: date-time
to_session_thread_id: string
Public sthr_ ID of the thread the message was sent to.
to_agent_name: optional string or null
Name of the callable agent this message was sent to. Absent when sent to the primary agent.
BetaManagedAgentsAgentThreadContextCompactedEvent object
Indicates that context compaction (summarization) occurred during the session.
type: "agent.thread_context_compacted"
id: string
Unique identifier for this event.
processed_at: string
Timestamp when compaction was processed.
format: date-time
BetaManagedAgentsSessionErrorEvent object
An error event indicating a problem occurred during session execution.
type: "session.error"
id: string
Unique identifier for this event.
error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 5 more
BetaManagedAgentsUnknownError object
An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on retry_status and message alone.
type: "unknown_error"
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
type: "retrying"
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
type: "exhausted"
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
type: "terminal"
BetaManagedAgentsModelOverloadedError object
The model is currently overloaded. Emitted after automatic retries are exhausted.
type: "model_overloaded_error"
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
BetaManagedAgentsModelRateLimitedError object
The model request was rate-limited.
type: "model_rate_limited_error"
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
BetaManagedAgentsModelRequestFailedError object
A model request failed for a reason other than overload or rate-limiting.
type: "model_request_failed_error"
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
BetaManagedAgentsMCPConnectionFailedError object
Failed to connect to an MCP server.
type: "mcp_connection_failed_error"
mcp_server_name: string
Name of the MCP server that failed to connect.
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
BetaManagedAgentsMCPAuthenticationFailedError object
Authentication to an MCP server failed.
type: "mcp_authentication_failed_error"
mcp_server_name: string
Name of the MCP server that failed authentication.
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
BetaManagedAgentsBillingError object
The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state.
type: "billing_error"
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
BetaManagedAgentsCredentialHostUnreachableError object
An environment_variable credential's auth.networking.allowed_hosts includes a host the environment's network policy does not permit.
type: "credential_host_unreachable_error"
credential_id: string
ID of the affected credential.
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
vault_id: string
ID of the vault containing the affected credential.
processed_at: string
Timestamp when the error occurred.
format: date-time
BetaManagedAgentsSessionStatusRescheduledEvent object
Indicates the session is recovering from an error state and is rescheduled for execution.
type: "session.status_rescheduled"
id: string
Unique identifier for this event.
processed_at: string
Timestamp of status change.
format: date-time
BetaManagedAgentsSessionStatusRunningEvent object
Indicates the session is actively running and the agent is working.
type: "session.status_running"
id: string
Unique identifier for this event.
processed_at: string
Timestamp of status change.
format: date-time
BetaManagedAgentsSessionStatusIdleEvent object
Indicates the agent has paused and is awaiting user input.
type: "session.status_idle"
id: string
Unique identifier for this event.
processed_at: string
Timestamp of status change.
format: date-time
stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached
BetaManagedAgentsSessionEndTurn object
The agent completed its turn naturally and is ready for the next user message.
type: "end_turn"
BetaManagedAgentsSessionRequiresAction object
The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.
type: "requires_action"
event_ids: array of string
The ids of events the agent is blocked on. Resolving fewer than all re-emits session.status_idle with the remainder.
BetaManagedAgentsSessionRetriesExhausted object
The turn ended because repeated errors exhausted the retry budget or an error escalated to retry_status: 'exhausted'.
type: "retries_exhausted"
BetaManagedAgentsSessionBudgetReached object
The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget.
type: "budget_reached"
BetaManagedAgentsSessionStatusTerminatedEvent object
Indicates the session has terminated, either due to an error or completion.
type: "session.status_terminated"
id: string
Unique identifier for this event.
processed_at: string
Timestamp of status change.
format: date-time
BetaManagedAgentsSessionThreadCreatedEvent object
Emitted when a subagent is spawned as a new thread. Written to the parent thread's output stream so clients observing the session see child creation.
type: "session.thread_created"
id: string
Unique identifier for this event.
agent_name: string
Name of the callable agent the thread runs.
processed_at: string
Timestamp when the thread was created.
format: date-time
session_thread_id: string
Public sthr_ ID of the newly created thread.
BetaManagedAgentsSpanOutcomeEvaluationStartEvent object
Emitted when an outcome evaluation cycle begins.
type: "span.outcome_evaluation_start"
id: string
Unique identifier for this event.
iteration: number
0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.
format: int32
outcome_id: string
The outc_ ID of the outcome being evaluated.
processed_at: string
Timestamp when outcome evaluation started.
format: date-time
BetaManagedAgentsSpanOutcomeEvaluationEndEvent object
Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of needs_revision means another evaluation cycle follows; satisfied, max_iterations_reached, failed, or interrupted are terminal — no further evaluation cycles follow.
type: "span.outcome_evaluation_end"
id: string
Unique identifier for this event.
explanation: string
Human-readable explanation of the verdict. For needs_revision, describes which criteria failed and why.
iteration: number
0-indexed revision cycle, matching the corresponding span.outcome_evaluation_start.
format: int32
outcome_evaluation_start_id: string
The id of the corresponding span.outcome_evaluation_start event.
outcome_id: string
The outc_ ID of the outcome being evaluated.
processed_at: string
Timestamp when outcome evaluation ended.
format: date-time
result: string
Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress.
usage: BetaManagedAgentsSpanModelUsage
Aggregate token usage for this evaluation cycle. Sums across all grader model requests within the cycle.
cache_creation_input_tokens: number
Tokens used to create prompt cache in this request.
format: int32
cache_read_input_tokens: number
Tokens read from prompt cache in this request.
format: int32
input_tokens: number
Input tokens consumed by this request.
format: int32
output_tokens: number
Output tokens generated by this request.
format: int32
speed: optional "standard" or "fast" or null
Inference speed tier this request actually ran at. Mirrors usage.speed on /v1/messages. Only present when the fast-mode beta is active.
"standard"
"fast"
BetaManagedAgentsSpanModelRequestStartEvent object
Emitted when a model request is initiated by the agent.
type: "span.model_request_start"
id: string
Unique identifier for this event.
processed_at: string
Timestamp when the model request started.
format: date-time
BetaManagedAgentsSpanModelRequestEndEvent object
Emitted when a model request completes.
type: "span.model_request_end"
id: string
Unique identifier for this event.
is_error: boolean or null
Whether the model request resulted in an error.
model_request_start_id: string
The id of the corresponding span.model_request_start event.
model_usage: BetaManagedAgentsSpanModelUsage
Token usage for this model request.
processed_at: string
Timestamp when the model request completed.
format: date-time
BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object
Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding span.outcome_evaluation_start and span.outcome_evaluation_end events.
type: "span.outcome_evaluation_ongoing"
id: string
Unique identifier for this event.
iteration: number
0-indexed revision cycle, matching the corresponding span.outcome_evaluation_start.
format: int32
outcome_id: string
The outc_ ID of the outcome being evaluated.
processed_at: string
Timestamp when this heartbeat was emitted.
format: date-time
BetaManagedAgentsUserDefineOutcomeEvent object
Echo of a user.define_outcome input event. Carries the server-generated outcome_id that subsequent span.outcome_evaluation_* events reference.
type: "user.define_outcome"
id: string
Unique identifier for this event.
description: string
What the agent should produce. Copied from the input event.
max_iterations: number or null
Evaluate-then-revise cycles before giving up. Default 3, max 20.
format: int32
outcome_id: string
Server-generated outc_ ID for this outcome. Referenced by span.outcome_evaluation_* events and the session's outcome_evaluations list.
processed_at: string
Timestamp when the outcome was accepted.
format: date-time
rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric
How to grade the outcome. File rubrics are currently resolved to their text content; clients should handle both variants.
BetaManagedAgentsFileRubric object
Rubric referenced by a file uploaded via the Files API.
type: "file"
file_id: string
ID of the rubric file.
BetaManagedAgentsTextRubric object
Rubric content provided inline as text.
type: "text"
content: string
Rubric content. Plain text or markdown — the grader treats it as freeform text.
BetaManagedAgentsSessionDeletedEvent object
Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.
type: "session.deleted"
id: string
Unique identifier for this event.
processed_at: string
Timestamp when the session was deleted.
format: date-time
BetaManagedAgentsSessionThreadStatusRunningEvent object
A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
type: "session.thread_status_running"
id: string
Unique identifier for this event.
agent_name: string
Name of the agent the thread runs.
processed_at: string
Timestamp of the status transition.
format: date-time
session_thread_id: string
Public sthr_ ID of the thread that started running.
BetaManagedAgentsSessionThreadStatusIdleEvent object
A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
type: "session.thread_status_idle"
id: string
Unique identifier for this event.
agent_name: string
Name of the agent the thread runs.
processed_at: string
Timestamp of the status transition.
format: date-time
session_thread_id: string
Public sthr_ ID of the thread that went idle.
stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached
BetaManagedAgentsSessionEndTurn object
The agent completed its turn naturally and is ready for the next user message.
BetaManagedAgentsSessionRequiresAction object
The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.
BetaManagedAgentsSessionRetriesExhausted object
The turn ended because repeated errors exhausted the retry budget or an error escalated to retry_status: 'exhausted'.
BetaManagedAgentsSessionBudgetReached object
The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget.
BetaManagedAgentsSessionThreadStatusTerminatedEvent object
A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
type: "session.thread_status_terminated"
id: string
Unique identifier for this event.
agent_name: string
Name of the agent the thread runs.
processed_at: string
Timestamp of the status transition.
format: date-time
session_thread_id: string
Public sthr_ ID of the thread that terminated.
BetaManagedAgentsUserToolResultEvent object
Event sent by the client providing the result of an agent-toolset tool execution. Only valid on self_hosted environments, where sandbox-routed tools are executed by the client rather than the server.
type: "user.tool_result"
id: string
Unique identifier for this event.
tool_use_id: string
The id of the agent.tool_use event this result corresponds to, which can be found in the last session.status_idle event's stop_reason.event_ids field.
content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock
The result content returned by the tool.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
BetaManagedAgentsSearchResultBlock object
A block containing a web search result.
is_error: optional boolean or null
Whether the tool execution resulted in an error.
processed_at: optional string or null
Timestamp when this result was processed.
format: date-time
session_thread_id: optional string or null
Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread.
BetaManagedAgentsSessionThreadStatusRescheduledEvent object
A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
type: "session.thread_status_rescheduled"
id: string
Unique identifier for this event.
agent_name: string
Name of the agent the thread runs.
processed_at: string
Timestamp of the status transition.
format: date-time
session_thread_id: string
Public sthr_ ID of the thread that is retrying.
BetaManagedAgentsSessionUpdatedEvent object
Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn.
type: "session.updated"
id: string
Unique identifier for this event.
processed_at: string
Timestamp when the update was applied.
format: date-time
agent: optional BetaManagedAgentsSessionAgent or null
The session's effective agent configuration after the update. Present only when the update changed agent (tools or mcp_servers); when present it is the full materialised snapshot, not a diff.
type: "agent"
id: string
description: string or null
mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition
type: "url"
name: string
url: string
model: BetaManagedAgentsModelConfig
Model identifier and configuration.
id: BetaManagedAgentsModel
The model that will power your agent.
See models for additional details and options.
string
"haijun-opus-5-5" or "haijun-fable-5-1" or "haijun-sonnet-5" or 12 more
The model that will power your agent.
See models for additional details and options.
"haijun-opus-5-5"
Powerful intelligence for coding, knowledge work, and long-running agents
"haijun-fable-5-1"
Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
"haijun-sonnet-5"
High-performance model for coding and agents
"haijun-fable-5"
Next generation of intelligence for the hardest knowledge work and coding problems
"haijun-opus-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-8"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-7"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-6"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-6"
Best combination of speed and intelligence
"haijun-haiku-4-5"
Fastest model with near-frontier intelligence
"haijun-haiku-4-5-20251001"
Fastest model with near-frontier intelligence
"haijun-opus-4-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-5-20251101"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-5"
High-performance model for agents and coding
"haijun-sonnet-4-5-20250929"
High-performance model for agents and coding
effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
How hard Haijun works on each inference call. One of low, medium, high, xhigh, max. Always present; resolved to the per-model default at save time when not supplied.
BetaManagedAgentsEffortLow object
Low effort. Favors latency over reasoning depth.
type: "low"
BetaManagedAgentsEffortMedium object
Medium effort. Balances latency and reasoning depth.
type: "medium"
BetaManagedAgentsEffortHigh object
High effort. Favors reasoning depth.
type: "high"
BetaManagedAgentsEffortXhigh object
Extra-high effort. Not all models accept this level.
type: "xhigh"
BetaManagedAgentsEffortMax object
Maximum effort. Favors reasoning depth over latency.
type: "max"
inference_geo: optional string
Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
speed: optional "standard" or "fast"
Inference speed mode. fast provides significantly faster output token generation at premium pricing. Defaults to standard. Not all models support fast; invalid combinations are rejected at create time.
"standard"
"fast"
multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null
Resolved multiagent orchestration configuration. Null when the agent is single-threaded.
type: "coordinator"
agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor
Full agent definitions the coordinator may spawn as session threads.
BetaManagedAgentsSessionThreadAgent object
Resolved agent definition for a single session_thread. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from Session.agent.
type: "agent"
id: string
description: string or null
mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition
type: "url"
name: string
url: string
model: BetaManagedAgentsModelConfig
Model identifier and configuration.
name: string
tracks: array of BetaManagedAgentsJuglowSkill or BetaManagedAgentsCustomSkill
BetaManagedAgentsJuglowSkill object
A resolved Juglow-managed track.
type: "juglow"
skill_id: string
version: string
BetaManagedAgentsCustomSkill object
A resolved user-created custom track.
type: "custom"
skill_id: string
version: string
system: string or null
tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool
BetaManagedAgentsAgentToolset20260401 object
type: "agent_toolset_20260401"
configs: array of BetaManagedAgentsAgentToolConfig
BetaManagedAgentsBashToolConfig object
Configuration for the bash tool.
type: "bash"
enabled: boolean
name: "bash"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
type: "always_allow"
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
type: "always_ask"
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
type: "auto"
BetaManagedAgentsEditToolConfig object
Configuration for the edit tool.
type: "edit"
enabled: boolean
name: "edit"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsReadToolConfig object
Configuration for the read tool.
type: "read"
enabled: boolean
name: "read"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWriteToolConfig object
Configuration for the write tool.
type: "write"
enabled: boolean
name: "write"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGlobToolConfig object
Configuration for the glob tool.
type: "glob"
enabled: boolean
name: "glob"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGrepToolConfig object
Configuration for the grep tool.
type: "grep"
enabled: boolean
name: "grep"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWebFetchToolConfig object
Configuration for the web_fetch tool.
type: "web_fetch"
enabled: boolean
name: "web_fetch"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
max_content_tokens: optional number or null
format: int32
BetaManagedAgentsWebSearchToolConfig object
Configuration for the web_search tool.
type: "web_search"
enabled: boolean
name: "web_search"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
user_location: optional BetaManagedAgentsUserLocation or null
Approximate user location for search result localization.
type: "approximate"
Location precision. Only "approximate" is supported.
city: optional string or null
City name.
minLength: 1, maxLength: 255
country: optional string or null
Two-letter ISO 3166-1 country code, uppercase.
region: optional string or null
Region or state name.
minLength: 1, maxLength: 255
timezone: optional string or null
IANA timezone identifier, e.g. "America/Los_Angeles".
minLength: 1, maxLength: 255
default_config: BetaManagedAgentsAgentToolsetDefaultConfig
Resolved default configuration for agent tools.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsMCPToolset object
type: "mcp_toolset"
configs: array of BetaManagedAgentsMCPToolConfig
enabled: boolean
name: string
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
default_config: BetaManagedAgentsMCPToolsetDefaultConfig
Resolved default configuration for all tools from an MCP server.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
mcp_server_name: string
BetaManagedAgentsCustomTool object
A custom tool as returned in API responses.
type: "custom"
description: string
input_schema: BetaManagedAgentsCustomToolInputSchema
JSON Schema for custom tool input parameters.
type: "object"
properties: optional map[unknown] or null
required: optional array of string or null
name: string
version: number
format: int32
BetaManagedAgentsAdvisor object
Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
type: "advisor"
model: string
The advisor model id.
name: string
tracks: array of BetaManagedAgentsJuglowSkill or BetaManagedAgentsCustomSkill
BetaManagedAgentsJuglowSkill object
A resolved Juglow-managed track.
BetaManagedAgentsCustomSkill object
A resolved user-created custom track.
system: string or null
tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool
BetaManagedAgentsAgentToolset20260401 object
BetaManagedAgentsMCPToolset object
BetaManagedAgentsCustomTool object
A custom tool as returned in API responses.
version: number
format: int32
budget: optional BetaManagedAgentsBudgetLimit or null
The session's budget after the update: the new budget when set or replaced, or null when the update removed it. Present only when the update changed the budget.
type: "limit"
max_list_cost: BetaMonetaryAmount
Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge.
amount: string
Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.
currency: BetaCurrency
Uppercase ISO-4217 currency code. USD is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.
metadata: optional map[string]
The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty.
title: optional string or null
The session's new title. Present only when the update changed it.
BetaManagedAgentsStartEvent object
Opens a preview of a buffered event. Carries the previewed event's type and id only. Followed by zero or more event_delta events with the same event id, normally concluded by the buffered event carrying that id. If the producing model request ends without that event (an error or interrupt mid-stream), its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history.
type: "event_start"
event: BetaManagedAgentsStartEventPreview
The previewed event's type and id. The event type determines which delta types the preview's event_delta events carry: agent.message events stream content_delta fragments; agent.thinking previews are start-only — no deltas follow, and the buffered agent.thinking with the same id concludes them.
BetaManagedAgentsAgentMessagePreview object
type: "agent.message"
id: string
The id the buffered agent.message will carry if it is emitted. Matches the event_id on this preview's event_delta events.
BetaManagedAgentsAgentThinkingPreview object
type: "agent.thinking"
id: string
The id the buffered agent.thinking will carry if it is emitted. Start-only — no event_delta events follow.
BetaManagedAgentsDeltaEvent object
An incremental update to an event that is still being streamed. Deltas are best-effort and may stop early; when the buffered event with id == event_id is produced it carries the complete content. A model request that ends early (an error or interrupt) produces no buffered event — its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history.
type: "event_delta"
delta: BetaManagedAgentsDeltaContent
One fragment of the previewed event. The delta type is named for the previewed event's field it streams into: agent.message events stream content_delta fragments, each a partial element of the content array.
type: "content_delta"
content: BetaManagedAgentsTextBlock
A partial element of the content array at index, typed like the element itself — the same shape the buffered agent.message carries in content.
index: optional number
Which entry in the previewed event's content array this fragment lands in. Insert content as that entry when the index is new; append to the existing entry otherwise.
event_id: string
The id of the event being previewed. Matches event.id on the corresponding event_start and the buffered event that reconciles the preview.
BetaManagedAgentsSystemMessageEvent object
A mid-conversation system message event. Carries system-role content that is appended to the session as a role: "system" turn.
type: "system.message"
id: string
Unique identifier for this event.
content: array of BetaManagedAgentsSystemContentBlock
System content blocks. Text-only.
type: "text"
text: string
The text content.
minLength: 1
processed_at: optional string or null
Timestamp when this system message was processed.
format: date-time
BetaManagedAgentsSessionUsageEvent object
Periodic snapshot of the session's cumulative usage and tracked list cost.
type: "session.usage"
id: string
Unique identifier for this event.
processed_at: string
Timestamp when the snapshot was taken.
format: date-time
usage: BetaManagedAgentsSessionUsageSnapshot
The session's cumulative usage at the snapshot time.
active_seconds: optional number
Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once. This is the duration the session's runtime cost is priced on.
format: double
cache_creation: optional BetaManagedAgentsCacheCreationUsage
Tokens used to create prompt cache entries, broken down by cache TTL.
ephemeral_1h_input_tokens: optional number
Tokens used to create 1-hour ephemeral cache entries.
format: int32
ephemeral_5m_input_tokens: optional number
Tokens used to create 5-minute ephemeral cache entries.
format: int32
cache_read_input_tokens: optional number
Total tokens read from prompt cache.
format: int32
input_tokens: optional number
Total input tokens consumed across all turns.
format: int32
list_cost: optional BetaMonetaryAmount
Cumulative list cost of the session across all turns, priced at public list rates.
output_tokens: optional number
Total output tokens generated across all turns.
format: int32
server_tool_use: optional BetaManagedAgentsServerToolUsage
Cumulative server-executed tool usage across all turns.
web_fetch_requests: optional number
Number of server-executed web fetch requests.
format: int32
web_search_requests: optional number
Number of server-executed web search requests.
format: int32
budget: optional BetaManagedAgentsBudgetLimit or null
The session's configured budget at the snapshot time, or null when the session has no budget.
Example
curl https://haijun.my.id/v1/sessions/$SESSION_ID/events/stream \
-H 'juglow-version: 2023-06-01' \
-H 'juglow-beta: managed-agents-2026-04-01' \
-H "X-Api-Key: $JUGLOW_API_KEY"Response (200)
{
"id": "sevt_011CZkZGOp0iBcp4kaQSihUmy",
"content": [
{
"text": "Where is my order #1234?",
"type": "text"
}
],
"type": "user.message",
"processed_at": "2026-03-15T10:00:00Z"
}Sessions › Resources
Add Session Resource
POST /v1/sessions/{session_id}/resources
Add Session Resource
Path parameters
session_id: string
Headers
"juglow-beta": optional array of JuglowBeta
Optional header to specify the beta version(s) you want to use.
string
"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 45 more
"message-batches-2024-09-24"
"prompt-caching-2024-07-31"
"computer-use-2024-10-22"
"computer-use-2025-01-24"
"pdfs-2024-09-25"
"token-counting-2024-11-01"
"token-efficient-tools-2025-02-19"
"output-128k-2025-02-19"
"files-api-2025-04-14"
"mcp-client-2025-04-04"
"mcp-client-2025-11-20"
"dev-full-thinking-2025-05-14"
"interleaved-thinking-2025-05-14"
"code-execution-2025-05-22"
"extended-cache-ttl-2025-04-11"
"context-1m-2025-08-07"
"context-management-2025-06-27"
"model-context-window-exceeded-2025-08-26"
"tracks-2025-10-02"
"fast-mode-2026-02-01"
"output-300k-2026-03-24"
"user-profiles-2026-03-24"
"user-profiles-2026-08-18"
"user-profiles-2026-09-04"
"advisor-tool-2026-03-01"
"managed-agents-2026-04-01"
"cache-diagnosis-2026-04-07"
"dreaming-2026-04-21"
"thinking-token-count-2026-05-13"
"server-side-fallback-2026-06-01"
"server-side-fallback-2026-07-01"
"fallback-credit-2026-06-01"
"fallback-credit-2026-07-01"
"agent-memory-2026-07-22"
"mid-conversation-tool-changes-2026-07-01"
"compact-2026-01-12"
"computer-use-2025-11-24"
"mcp-tunnels-2026-06-22"
"structured-outputs-2025-11-13"
"task-budgets-2026-03-13"
"thinking-display-updates-2026-08-18"
"ce-user-management-2026-07-13"
"mid-conversation-output-config-2026-07-01"
"thinking-binding-controls-2026-08-01"
"mid-conversation-system-clear-at-2026-08-21"
"compact-2026-09-04"
"inline-tools-2026-09-15"
"mcp-client-2026-09-15"
"juglow-workspace-id": optional string
Optional header to select the Workspace for this request. The value is a Workspace ID (for example, wrkspc_011CZkZaBF1tNoB5wlCeusgy).
Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.
Body parameters
file_id: string
ID of a previously uploaded file.
minLength: 1, maxLength: 128
type: "file"
mount_path: optional string or null
Mount path in the container. Defaults to /mnt/session/uploads/.
minLength: 1, maxLength: 4096
Returns
BetaManagedAgentsFileResource object
type: "file"
id: string
created_at: string
A timestamp in RFC 3339 format
format: date-time
file_id: string
mount_path: string
updated_at: string
A timestamp in RFC 3339 format
format: date-time
Example
curl https://haijun.my.id/v1/sessions/$SESSION_ID/resources \
-H 'Content-Type: application/json' \
-H 'juglow-version: 2023-06-01' \
-H 'juglow-beta: managed-agents-2026-04-01' \
-H "X-Api-Key: $JUGLOW_API_KEY" \
-d '{
"file_id": "file_011CNha8iCJcU1wXNR6q4V8w",
"type": "file",
"mount_path": "/uploads/receipt.pdf"
}'Response (200)
{
"id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht",
"created_at": "2026-03-15T10:00:00Z",
"file_id": "file_011CNha8iCJcU1wXNR6q4V8w",
"mount_path": "/uploads/receipt.pdf",
"type": "file",
"updated_at": "2026-03-15T10:00:00Z"
}List Session Resources
GET /v1/sessions/{session_id}/resources
List Session Resources
Path parameters
session_id: string
Query parameters
limit: optional number
Maximum number of resources to return per page (max 1000). If omitted, returns all resources.
format: int32
page: optional string
Opaque cursor from a previous response's next_page field.
Headers
"juglow-beta": optional array of JuglowBeta
Optional header to specify the beta version(s) you want to use.
string
"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 45 more
"message-batches-2024-09-24"
"prompt-caching-2024-07-31"
"computer-use-2024-10-22"
"computer-use-2025-01-24"
"pdfs-2024-09-25"
"token-counting-2024-11-01"
"token-efficient-tools-2025-02-19"
"output-128k-2025-02-19"
"files-api-2025-04-14"
"mcp-client-2025-04-04"
"mcp-client-2025-11-20"
"dev-full-thinking-2025-05-14"
"interleaved-thinking-2025-05-14"
"code-execution-2025-05-22"
"extended-cache-ttl-2025-04-11"
"context-1m-2025-08-07"
"context-management-2025-06-27"
"model-context-window-exceeded-2025-08-26"
"tracks-2025-10-02"
"fast-mode-2026-02-01"
"output-300k-2026-03-24"
"user-profiles-2026-03-24"
"user-profiles-2026-08-18"
"user-profiles-2026-09-04"
"advisor-tool-2026-03-01"
"managed-agents-2026-04-01"
"cache-diagnosis-2026-04-07"
"dreaming-2026-04-21"
"thinking-token-count-2026-05-13"
"server-side-fallback-2026-06-01"
"server-side-fallback-2026-07-01"
"fallback-credit-2026-06-01"
"fallback-credit-2026-07-01"
"agent-memory-2026-07-22"
"mid-conversation-tool-changes-2026-07-01"
"compact-2026-01-12"
"computer-use-2025-11-24"
"mcp-tunnels-2026-06-22"
"structured-outputs-2025-11-13"
"task-budgets-2026-03-13"
"thinking-display-updates-2026-08-18"
"ce-user-management-2026-07-13"
"mid-conversation-output-config-2026-07-01"
"thinking-binding-controls-2026-08-01"
"mid-conversation-system-clear-at-2026-08-21"
"compact-2026-09-04"
"inline-tools-2026-09-15"
"mcp-client-2026-09-15"
"juglow-workspace-id": optional string
Optional header to select the Workspace for this request. The value is a Workspace ID (for example, wrkspc_011CZkZaBF1tNoB5wlCeusgy).
Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.
Returns
data: array of BetaManagedAgentsSessionResource
Resources for the session, ordered by created_at.
BetaManagedAgentsGitHubRepositoryResource object
type: "github_repository"
id: string
created_at: string
A timestamp in RFC 3339 format
format: date-time
mount_path: string
updated_at: string
A timestamp in RFC 3339 format
format: date-time
url: string
checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null
BetaManagedAgentsBranchCheckout object
type: "branch"
name: string
Branch name to check out.
minLength: 1, maxLength: 255
BetaManagedAgentsCommitCheckout object
type: "commit"
sha: string
Full commit SHA to check out.
minLength: 7, maxLength: 64
BetaManagedAgentsFileResource object
type: "file"
id: string
created_at: string
A timestamp in RFC 3339 format
format: date-time
file_id: string
mount_path: string
updated_at: string
A timestamp in RFC 3339 format
format: date-time
BetaManagedAgentsMemoryStoreResource object
A memory store attached to an agent session.
type: "memory_store"
memory_store_id: string
The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
access: optional "read_write" or "read_only" or null
Access mode for the mounted store. Defaults to read_write. read_only mounts the store as a read-only filesystem.
"read_write"
"read_only"
description: optional string
Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description.
instructions: optional string or null
Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
maxLength: 4096
mount_path: optional string or null
Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only.
name: optional string or null
Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource.
next_page: optional string or null
Opaque cursor for the next page. Null when no more results.
Example
curl https://haijun.my.id/v1/sessions/$SESSION_ID/resources \
-H 'juglow-version: 2023-06-01' \
-H 'juglow-beta: managed-agents-2026-04-01' \
-H "X-Api-Key: $JUGLOW_API_KEY"Response (200)
{
"data": [
{
"id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht",
"created_at": "2026-03-15T10:00:00Z",
"file_id": "file_011CNha8iCJcU1wXNR6q4V8w",
"mount_path": "/uploads/receipt.pdf",
"type": "file",
"updated_at": "2026-03-15T10:00:00Z"
},
{
"id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu",
"created_at": "2026-03-15T10:00:00Z",
"mount_path": "/workspace/example-repo",
"type": "github_repository",
"updated_at": "2026-03-15T10:00:00Z",
"url": "https://github.com/example-org/example-repo",
"checkout": {
"name": "main",
"type": "branch"
}
}
],
"next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
}Get Session Resource
GET /v1/sessions/{session_id}/resources/{resource_id}
Get Session Resource
Path parameters
session_id: string
resource_id: string
Headers
"juglow-beta": optional array of JuglowBeta
Optional header to specify the beta version(s) you want to use.
string
"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 45 more
"message-batches-2024-09-24"
"prompt-caching-2024-07-31"
"computer-use-2024-10-22"
"computer-use-2025-01-24"
"pdfs-2024-09-25"
"token-counting-2024-11-01"
"token-efficient-tools-2025-02-19"
"output-128k-2025-02-19"
"files-api-2025-04-14"
"mcp-client-2025-04-04"
"mcp-client-2025-11-20"
"dev-full-thinking-2025-05-14"
"interleaved-thinking-2025-05-14"
"code-execution-2025-05-22"
"extended-cache-ttl-2025-04-11"
"context-1m-2025-08-07"
"context-management-2025-06-27"
"model-context-window-exceeded-2025-08-26"
"tracks-2025-10-02"
"fast-mode-2026-02-01"
"output-300k-2026-03-24"
"user-profiles-2026-03-24"
"user-profiles-2026-08-18"
"user-profiles-2026-09-04"
"advisor-tool-2026-03-01"
"managed-agents-2026-04-01"
"cache-diagnosis-2026-04-07"
"dreaming-2026-04-21"
"thinking-token-count-2026-05-13"
"server-side-fallback-2026-06-01"
"server-side-fallback-2026-07-01"
"fallback-credit-2026-06-01"
"fallback-credit-2026-07-01"
"agent-memory-2026-07-22"
"mid-conversation-tool-changes-2026-07-01"
"compact-2026-01-12"
"computer-use-2025-11-24"
"mcp-tunnels-2026-06-22"
"structured-outputs-2025-11-13"
"task-budgets-2026-03-13"
"thinking-display-updates-2026-08-18"
"ce-user-management-2026-07-13"
"mid-conversation-output-config-2026-07-01"
"thinking-binding-controls-2026-08-01"
"mid-conversation-system-clear-at-2026-08-21"
"compact-2026-09-04"
"inline-tools-2026-09-15"
"mcp-client-2026-09-15"
"juglow-workspace-id": optional string
Optional header to select the Workspace for this request. The value is a Workspace ID (for example, wrkspc_011CZkZaBF1tNoB5wlCeusgy).
Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.
Returns
BetaManagedAgentsGitHubRepositoryResource object
type: "github_repository"
id: string
created_at: string
A timestamp in RFC 3339 format
format: date-time
mount_path: string
updated_at: string
A timestamp in RFC 3339 format
format: date-time
url: string
checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null
BetaManagedAgentsBranchCheckout object
type: "branch"
name: string
Branch name to check out.
minLength: 1, maxLength: 255
BetaManagedAgentsCommitCheckout object
type: "commit"
sha: string
Full commit SHA to check out.
minLength: 7, maxLength: 64
BetaManagedAgentsFileResource object
type: "file"
id: string
created_at: string
A timestamp in RFC 3339 format
format: date-time
file_id: string
mount_path: string
updated_at: string
A timestamp in RFC 3339 format
format: date-time
BetaManagedAgentsMemoryStoreResource object
A memory store attached to an agent session.
type: "memory_store"
memory_store_id: string
The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
access: optional "read_write" or "read_only" or null
Access mode for the mounted store. Defaults to read_write. read_only mounts the store as a read-only filesystem.
"read_write"
"read_only"
description: optional string
Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description.
instructions: optional string or null
Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
maxLength: 4096
mount_path: optional string or null
Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only.
name: optional string or null
Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource.
Example
curl https://haijun.my.id/v1/sessions/$SESSION_ID/resources/$RESOURCE_ID \
-H 'juglow-version: 2023-06-01' \
-H 'juglow-beta: managed-agents-2026-04-01' \
-H "X-Api-Key: $JUGLOW_API_KEY"Response (200)
{
"id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu",
"created_at": "2026-03-15T10:00:00Z",
"mount_path": "/workspace/example-repo",
"type": "github_repository",
"updated_at": "2026-03-15T10:00:00Z",
"url": "https://github.com/example-org/example-repo",
"checkout": {
"name": "main",
"type": "branch"
}
}Update Session Resource
POST /v1/sessions/{session_id}/resources/{resource_id}
Update Session Resource
Path parameters
session_id: string
resource_id: string
Headers
"juglow-beta": optional array of JuglowBeta
Optional header to specify the beta version(s) you want to use.
string
"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 45 more
"message-batches-2024-09-24"
"prompt-caching-2024-07-31"
"computer-use-2024-10-22"
"computer-use-2025-01-24"
"pdfs-2024-09-25"
"token-counting-2024-11-01"
"token-efficient-tools-2025-02-19"
"output-128k-2025-02-19"
"files-api-2025-04-14"
"mcp-client-2025-04-04"
"mcp-client-2025-11-20"
"dev-full-thinking-2025-05-14"
"interleaved-thinking-2025-05-14"
"code-execution-2025-05-22"
"extended-cache-ttl-2025-04-11"
"context-1m-2025-08-07"
"context-management-2025-06-27"
"model-context-window-exceeded-2025-08-26"
"tracks-2025-10-02"
"fast-mode-2026-02-01"
"output-300k-2026-03-24"
"user-profiles-2026-03-24"
"user-profiles-2026-08-18"
"user-profiles-2026-09-04"
"advisor-tool-2026-03-01"
"managed-agents-2026-04-01"
"cache-diagnosis-2026-04-07"
"dreaming-2026-04-21"
"thinking-token-count-2026-05-13"
"server-side-fallback-2026-06-01"
"server-side-fallback-2026-07-01"
"fallback-credit-2026-06-01"
"fallback-credit-2026-07-01"
"agent-memory-2026-07-22"
"mid-conversation-tool-changes-2026-07-01"
"compact-2026-01-12"
"computer-use-2025-11-24"
"mcp-tunnels-2026-06-22"
"structured-outputs-2025-11-13"
"task-budgets-2026-03-13"
"thinking-display-updates-2026-08-18"
"ce-user-management-2026-07-13"
"mid-conversation-output-config-2026-07-01"
"thinking-binding-controls-2026-08-01"
"mid-conversation-system-clear-at-2026-08-21"
"compact-2026-09-04"
"inline-tools-2026-09-15"
"mcp-client-2026-09-15"
"juglow-workspace-id": optional string
Optional header to select the Workspace for this request. The value is a Workspace ID (for example, wrkspc_011CZkZaBF1tNoB5wlCeusgy).
Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.
Body parameters
authorization_token: string
New authorization token for the resource. Currently only github_repository resources support token rotation.
minLength: 1, maxLength: 4096
Returns
BetaManagedAgentsGitHubRepositoryResource object
type: "github_repository"
id: string
created_at: string
A timestamp in RFC 3339 format
format: date-time
mount_path: string
updated_at: string
A timestamp in RFC 3339 format
format: date-time
url: string
checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null
BetaManagedAgentsBranchCheckout object
type: "branch"
name: string
Branch name to check out.
minLength: 1, maxLength: 255
BetaManagedAgentsCommitCheckout object
type: "commit"
sha: string
Full commit SHA to check out.
minLength: 7, maxLength: 64
BetaManagedAgentsFileResource object
type: "file"
id: string
created_at: string
A timestamp in RFC 3339 format
format: date-time
file_id: string
mount_path: string
updated_at: string
A timestamp in RFC 3339 format
format: date-time
BetaManagedAgentsMemoryStoreResource object
A memory store attached to an agent session.
type: "memory_store"
memory_store_id: string
The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
access: optional "read_write" or "read_only" or null
Access mode for the mounted store. Defaults to read_write. read_only mounts the store as a read-only filesystem.
"read_write"
"read_only"
description: optional string
Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description.
instructions: optional string or null
Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
maxLength: 4096
mount_path: optional string or null
Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only.
name: optional string or null
Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource.
Example
curl https://haijun.my.id/v1/sessions/$SESSION_ID/resources/$RESOURCE_ID \
-H 'Content-Type: application/json' \
-H 'juglow-version: 2023-06-01' \
-H 'juglow-beta: managed-agents-2026-04-01' \
-H "X-Api-Key: $JUGLOW_API_KEY" \
-d '{
"authorization_token": "ghp_exampletoken"
}'Response (200)
{
"id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu",
"created_at": "2026-03-15T10:00:00Z",
"mount_path": "/workspace/example-repo",
"type": "github_repository",
"updated_at": "2026-03-15T10:00:00Z",
"url": "https://github.com/example-org/example-repo",
"checkout": {
"name": "main",
"type": "branch"
}
}Delete Session Resource
DELETE /v1/sessions/{session_id}/resources/{resource_id}
Delete Session Resource
Path parameters
session_id: string
resource_id: string
Headers
"juglow-beta": optional array of JuglowBeta
Optional header to specify the beta version(s) you want to use.
string
"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 45 more
"message-batches-2024-09-24"
"prompt-caching-2024-07-31"
"computer-use-2024-10-22"
"computer-use-2025-01-24"
"pdfs-2024-09-25"
"token-counting-2024-11-01"
"token-efficient-tools-2025-02-19"
"output-128k-2025-02-19"
"files-api-2025-04-14"
"mcp-client-2025-04-04"
"mcp-client-2025-11-20"
"dev-full-thinking-2025-05-14"
"interleaved-thinking-2025-05-14"
"code-execution-2025-05-22"
"extended-cache-ttl-2025-04-11"
"context-1m-2025-08-07"
"context-management-2025-06-27"
"model-context-window-exceeded-2025-08-26"
"tracks-2025-10-02"
"fast-mode-2026-02-01"
"output-300k-2026-03-24"
"user-profiles-2026-03-24"
"user-profiles-2026-08-18"
"user-profiles-2026-09-04"
"advisor-tool-2026-03-01"
"managed-agents-2026-04-01"
"cache-diagnosis-2026-04-07"
"dreaming-2026-04-21"
"thinking-token-count-2026-05-13"
"server-side-fallback-2026-06-01"
"server-side-fallback-2026-07-01"
"fallback-credit-2026-06-01"
"fallback-credit-2026-07-01"
"agent-memory-2026-07-22"
"mid-conversation-tool-changes-2026-07-01"
"compact-2026-01-12"
"computer-use-2025-11-24"
"mcp-tunnels-2026-06-22"
"structured-outputs-2025-11-13"
"task-budgets-2026-03-13"
"thinking-display-updates-2026-08-18"
"ce-user-management-2026-07-13"
"mid-conversation-output-config-2026-07-01"
"thinking-binding-controls-2026-08-01"
"mid-conversation-system-clear-at-2026-08-21"
"compact-2026-09-04"
"inline-tools-2026-09-15"
"mcp-client-2026-09-15"
"juglow-workspace-id": optional string
Optional header to select the Workspace for this request. The value is a Workspace ID (for example, wrkspc_011CZkZaBF1tNoB5wlCeusgy).
Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.
Returns
BetaManagedAgentsDeleteSessionResource object
Confirmation of resource deletion.
type: "session_resource_deleted"
id: string
Example
curl https://haijun.my.id/v1/sessions/$SESSION_ID/resources/$RESOURCE_ID \
-X DELETE \
-H 'juglow-version: 2023-06-01' \
-H 'juglow-beta: managed-agents-2026-04-01' \
-H "X-Api-Key: $JUGLOW_API_KEY"Response (200)
{
"id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht",
"type": "session_resource_deleted"
}Sessions › Threads
List Session Threads
GET /v1/sessions/{session_id}/threads
List Session Threads
Path parameters
session_id: string
Query parameters
limit: optional number
Maximum results per page. Defaults to 1000.
format: int32
page: optional string
Opaque pagination cursor from a previous response's next_page. Forward-only.
Headers
"juglow-beta": optional array of JuglowBeta
Optional header to specify the beta version(s) you want to use.
string
"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 45 more
"message-batches-2024-09-24"
"prompt-caching-2024-07-31"
"computer-use-2024-10-22"
"computer-use-2025-01-24"
"pdfs-2024-09-25"
"token-counting-2024-11-01"
"token-efficient-tools-2025-02-19"
"output-128k-2025-02-19"
"files-api-2025-04-14"
"mcp-client-2025-04-04"
"mcp-client-2025-11-20"
"dev-full-thinking-2025-05-14"
"interleaved-thinking-2025-05-14"
"code-execution-2025-05-22"
"extended-cache-ttl-2025-04-11"
"context-1m-2025-08-07"
"context-management-2025-06-27"
"model-context-window-exceeded-2025-08-26"
"tracks-2025-10-02"
"fast-mode-2026-02-01"
"output-300k-2026-03-24"
"user-profiles-2026-03-24"
"user-profiles-2026-08-18"
"user-profiles-2026-09-04"
"advisor-tool-2026-03-01"
"managed-agents-2026-04-01"
"cache-diagnosis-2026-04-07"
"dreaming-2026-04-21"
"thinking-token-count-2026-05-13"
"server-side-fallback-2026-06-01"
"server-side-fallback-2026-07-01"
"fallback-credit-2026-06-01"
"fallback-credit-2026-07-01"
"agent-memory-2026-07-22"
"mid-conversation-tool-changes-2026-07-01"
"compact-2026-01-12"
"computer-use-2025-11-24"
"mcp-tunnels-2026-06-22"
"structured-outputs-2025-11-13"
"task-budgets-2026-03-13"
"thinking-display-updates-2026-08-18"
"ce-user-management-2026-07-13"
"mid-conversation-output-config-2026-07-01"
"thinking-binding-controls-2026-08-01"
"mid-conversation-system-clear-at-2026-08-21"
"compact-2026-09-04"
"inline-tools-2026-09-15"
"mcp-client-2026-09-15"
"juglow-workspace-id": optional string
Optional header to select the Workspace for this request. The value is a Workspace ID (for example, wrkspc_011CZkZaBF1tNoB5wlCeusgy).
Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.
Returns
data: optional array of BetaManagedAgentsSessionThread
Threads in the session, primary first then children in spawn order.
type: "session_thread"
id: string
Unique identifier for this thread.
agent: BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor
Resolved agent definition for this thread. Snapshot of the agent at thread creation time.
BetaManagedAgentsSessionThreadAgent object
Resolved agent definition for a single session_thread. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from Session.agent.
type: "agent"
id: string
description: string or null
mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition
type: "url"
name: string
url: string
model: BetaManagedAgentsModelConfig
Model identifier and configuration.
id: BetaManagedAgentsModel
The model that will power your agent.
See models for additional details and options.
string
"haijun-opus-5-5" or "haijun-fable-5-1" or "haijun-sonnet-5" or 12 more
The model that will power your agent.
See models for additional details and options.
"haijun-opus-5-5"
Powerful intelligence for coding, knowledge work, and long-running agents
"haijun-fable-5-1"
Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
"haijun-sonnet-5"
High-performance model for coding and agents
"haijun-fable-5"
Next generation of intelligence for the hardest knowledge work and coding problems
"haijun-opus-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-8"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-7"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-6"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-6"
Best combination of speed and intelligence
"haijun-haiku-4-5"
Fastest model with near-frontier intelligence
"haijun-haiku-4-5-20251001"
Fastest model with near-frontier intelligence
"haijun-opus-4-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-5-20251101"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-5"
High-performance model for agents and coding
"haijun-sonnet-4-5-20250929"
High-performance model for agents and coding
effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
How hard Haijun works on each inference call. One of low, medium, high, xhigh, max. Always present; resolved to the per-model default at save time when not supplied.
BetaManagedAgentsEffortLow object
Low effort. Favors latency over reasoning depth.
type: "low"
BetaManagedAgentsEffortMedium object
Medium effort. Balances latency and reasoning depth.
type: "medium"
BetaManagedAgentsEffortHigh object
High effort. Favors reasoning depth.
type: "high"
BetaManagedAgentsEffortXhigh object
Extra-high effort. Not all models accept this level.
type: "xhigh"
BetaManagedAgentsEffortMax object
Maximum effort. Favors reasoning depth over latency.
type: "max"
inference_geo: optional string
Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
speed: optional "standard" or "fast"
Inference speed mode. fast provides significantly faster output token generation at premium pricing. Defaults to standard. Not all models support fast; invalid combinations are rejected at create time.
"standard"
"fast"
name: string
tracks: array of BetaManagedAgentsJuglowSkill or BetaManagedAgentsCustomSkill
BetaManagedAgentsJuglowSkill object
A resolved Juglow-managed track.
type: "juglow"
skill_id: string
version: string
BetaManagedAgentsCustomSkill object
A resolved user-created custom track.
type: "custom"
skill_id: string
version: string
system: string or null
tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool
BetaManagedAgentsAgentToolset20260401 object
type: "agent_toolset_20260401"
configs: array of BetaManagedAgentsAgentToolConfig
BetaManagedAgentsBashToolConfig object
Configuration for the bash tool.
type: "bash"
enabled: boolean
name: "bash"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
type: "always_allow"
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
type: "always_ask"
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
type: "auto"
BetaManagedAgentsEditToolConfig object
Configuration for the edit tool.
type: "edit"
enabled: boolean
name: "edit"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsReadToolConfig object
Configuration for the read tool.
type: "read"
enabled: boolean
name: "read"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWriteToolConfig object
Configuration for the write tool.
type: "write"
enabled: boolean
name: "write"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGlobToolConfig object
Configuration for the glob tool.
type: "glob"
enabled: boolean
name: "glob"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGrepToolConfig object
Configuration for the grep tool.
type: "grep"
enabled: boolean
name: "grep"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWebFetchToolConfig object
Configuration for the web_fetch tool.
type: "web_fetch"
enabled: boolean
name: "web_fetch"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
max_content_tokens: optional number or null
format: int32
BetaManagedAgentsWebSearchToolConfig object
Configuration for the web_search tool.
type: "web_search"
enabled: boolean
name: "web_search"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
user_location: optional BetaManagedAgentsUserLocation or null
Approximate user location for search result localization.
type: "approximate"
Location precision. Only "approximate" is supported.
city: optional string or null
City name.
minLength: 1, maxLength: 255
country: optional string or null
Two-letter ISO 3166-1 country code, uppercase.
region: optional string or null
Region or state name.
minLength: 1, maxLength: 255
timezone: optional string or null
IANA timezone identifier, e.g. "America/Los_Angeles".
minLength: 1, maxLength: 255
default_config: BetaManagedAgentsAgentToolsetDefaultConfig
Resolved default configuration for agent tools.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsMCPToolset object
type: "mcp_toolset"
configs: array of BetaManagedAgentsMCPToolConfig
enabled: boolean
name: string
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
default_config: BetaManagedAgentsMCPToolsetDefaultConfig
Resolved default configuration for all tools from an MCP server.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
mcp_server_name: string
BetaManagedAgentsCustomTool object
A custom tool as returned in API responses.
type: "custom"
description: string
input_schema: BetaManagedAgentsCustomToolInputSchema
JSON Schema for custom tool input parameters.
type: "object"
properties: optional map[unknown] or null
required: optional array of string or null
name: string
version: number
format: int32
BetaManagedAgentsAdvisor object
Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
type: "advisor"
model: string
The advisor model id.
archived_at: string or null
When the thread was archived. Null if not archived.
format: date-time
created_at: string
When the thread was created.
format: date-time
parent_thread_id: string or null
Parent thread that spawned this thread. Null for the primary thread.
session_id: string
The session this thread belongs to.
stats: BetaManagedAgentsSessionThreadStats or null
Timing statistics for this thread. Null until the thread's first status transition.
active_seconds: optional number
Cumulative time in seconds the thread spent actively running. Excludes idle time.
format: double
duration_seconds: optional number
Elapsed time since thread creation in seconds. For archived threads, frozen at the final update.
format: double
startup_seconds: optional number
Time in seconds for the thread to begin running. Zero for child threads, which start immediately.
format: double
status: BetaManagedAgentsSessionThreadStatus
Current execution status of the thread.
"running"
"idle"
"rescheduling"
"terminated"
updated_at: string
When the thread was last updated.
format: date-time
usage: BetaManagedAgentsSessionThreadUsage or null
Cumulative token usage for this thread. Null until the thread's first idle transition.
active_seconds: optional number
Cumulative time in seconds this thread spent in running status. Equal to stats.active_seconds; surfaced here so a thread's usage carries every quantity its cost is priced on.
format: double
cache_creation: optional BetaManagedAgentsCacheCreationUsage
Tokens used to create prompt cache entries, broken down by cache TTL.
ephemeral_1h_input_tokens: optional number
Tokens used to create 1-hour ephemeral cache entries.
format: int32
ephemeral_5m_input_tokens: optional number
Tokens used to create 5-minute ephemeral cache entries.
format: int32
cache_read_input_tokens: optional number
Total tokens read from prompt cache.
format: int32
input_tokens: optional number
Total input tokens consumed across all turns.
format: int32
list_cost: optional BetaMonetaryAmount or null
Cumulative list cost of this thread across all turns, priced at public list rates. Absent until cost tracking is available for the thread. Each figure is rounded to the nearest cent independently and the session's aggregate usage.list_cost additionally includes session runtime, so per-thread costs do not sum exactly to the session figure; the session figure is authoritative and is what a budget is enforced against.
amount: string
Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.
currency: BetaCurrency
Uppercase ISO-4217 currency code. USD is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.
output_tokens: optional number
Total output tokens generated across all turns.
format: int32
server_tool_use: optional BetaManagedAgentsServerToolUsage or null
Cumulative server-executed tool usage across all turns of this thread. Absent until server-tool tracking is available for the thread.
web_fetch_requests: optional number
Number of server-executed web fetch requests.
format: int32
web_search_requests: optional number
Number of server-executed web search requests.
format: int32
next_page: optional string or null
Opaque cursor for the next page. Null when no more results.
Example
curl https://haijun.my.id/v1/sessions/$SESSION_ID/threads \
-H 'juglow-version: 2023-06-01' \
-H 'juglow-beta: managed-agents-2026-04-01' \
-H "X-Api-Key: $JUGLOW_API_KEY"Response (200)
{
"data": [
{
"id": "sthr_011CZkZVWa6oIjw0rgXZpnBt",
"agent": {
"id": "agent_011CZkYqphY8vELVzwCUpqiQ",
"description": "A focused research subagent.",
"mcp_servers": [
{
"name": "example-mcp",
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse"
}
],
"model": {
"id": "haijun-opus-5",
"effort": {
"type": "low"
},
"inference_geo": "inference_geo",
"speed": "standard"
},
"name": "Researcher",
"tracks": [
{
"skill_id": "xlsx",
"type": "juglow",
"version": "1"
}
],
"system": "You are a research subagent that gathers and summarises sources for the coordinating agent.",
"tools": [
{
"configs": [
{
"enabled": true,
"name": "bash",
"permission_policy": {
"type": "always_allow"
},
"type": "bash"
}
],
"default_config": {
"enabled": true,
"permission_policy": {
"type": "always_ask"
}
},
"type": "agent_toolset_20260401"
}
],
"type": "agent",
"version": 1
},
"archived_at": null,
"created_at": "2026-03-15T10:00:00Z",
"parent_thread_id": null,
"session_id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
"stats": {
"active_seconds": 0,
"duration_seconds": 0,
"startup_seconds": 0
},
"status": "idle",
"type": "session_thread",
"updated_at": "2026-03-15T10:00:00Z",
"usage": {
"active_seconds": 0,
"cache_creation": {
"ephemeral_1h_input_tokens": 0,
"ephemeral_5m_input_tokens": 0
},
"cache_read_input_tokens": 0,
"input_tokens": 0,
"list_cost": {
"amount": "2500",
"currency": "USD"
},
"output_tokens": 0,
"server_tool_use": {
"web_fetch_requests": 0,
"web_search_requests": 3
}
}
}
],
"next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
}Get Session Thread
GET /v1/sessions/{session_id}/threads/{thread_id}
Get Session Thread
Path parameters
session_id: string
thread_id: string
Headers
"juglow-beta": optional array of JuglowBeta
Optional header to specify the beta version(s) you want to use.
string
"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 45 more
"message-batches-2024-09-24"
"prompt-caching-2024-07-31"
"computer-use-2024-10-22"
"computer-use-2025-01-24"
"pdfs-2024-09-25"
"token-counting-2024-11-01"
"token-efficient-tools-2025-02-19"
"output-128k-2025-02-19"
"files-api-2025-04-14"
"mcp-client-2025-04-04"
"mcp-client-2025-11-20"
"dev-full-thinking-2025-05-14"
"interleaved-thinking-2025-05-14"
"code-execution-2025-05-22"
"extended-cache-ttl-2025-04-11"
"context-1m-2025-08-07"
"context-management-2025-06-27"
"model-context-window-exceeded-2025-08-26"
"tracks-2025-10-02"
"fast-mode-2026-02-01"
"output-300k-2026-03-24"
"user-profiles-2026-03-24"
"user-profiles-2026-08-18"
"user-profiles-2026-09-04"
"advisor-tool-2026-03-01"
"managed-agents-2026-04-01"
"cache-diagnosis-2026-04-07"
"dreaming-2026-04-21"
"thinking-token-count-2026-05-13"
"server-side-fallback-2026-06-01"
"server-side-fallback-2026-07-01"
"fallback-credit-2026-06-01"
"fallback-credit-2026-07-01"
"agent-memory-2026-07-22"
"mid-conversation-tool-changes-2026-07-01"
"compact-2026-01-12"
"computer-use-2025-11-24"
"mcp-tunnels-2026-06-22"
"structured-outputs-2025-11-13"
"task-budgets-2026-03-13"
"thinking-display-updates-2026-08-18"
"ce-user-management-2026-07-13"
"mid-conversation-output-config-2026-07-01"
"thinking-binding-controls-2026-08-01"
"mid-conversation-system-clear-at-2026-08-21"
"compact-2026-09-04"
"inline-tools-2026-09-15"
"mcp-client-2026-09-15"
"juglow-workspace-id": optional string
Optional header to select the Workspace for this request. The value is a Workspace ID (for example, wrkspc_011CZkZaBF1tNoB5wlCeusgy).
Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.
Returns
BetaManagedAgentsSessionThread object
An execution thread within a session. Each session has one primary thread plus zero or more child threads spawned by the coordinator.
type: "session_thread"
id: string
Unique identifier for this thread.
agent: BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor
Resolved agent definition for this thread. Snapshot of the agent at thread creation time.
BetaManagedAgentsSessionThreadAgent object
Resolved agent definition for a single session_thread. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from Session.agent.
type: "agent"
id: string
description: string or null
mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition
type: "url"
name: string
url: string
model: BetaManagedAgentsModelConfig
Model identifier and configuration.
id: BetaManagedAgentsModel
The model that will power your agent.
See models for additional details and options.
string
"haijun-opus-5-5" or "haijun-fable-5-1" or "haijun-sonnet-5" or 12 more
The model that will power your agent.
See models for additional details and options.
"haijun-opus-5-5"
Powerful intelligence for coding, knowledge work, and long-running agents
"haijun-fable-5-1"
Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
"haijun-sonnet-5"
High-performance model for coding and agents
"haijun-fable-5"
Next generation of intelligence for the hardest knowledge work and coding problems
"haijun-opus-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-8"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-7"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-6"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-6"
Best combination of speed and intelligence
"haijun-haiku-4-5"
Fastest model with near-frontier intelligence
"haijun-haiku-4-5-20251001"
Fastest model with near-frontier intelligence
"haijun-opus-4-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-5-20251101"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-5"
High-performance model for agents and coding
"haijun-sonnet-4-5-20250929"
High-performance model for agents and coding
effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
How hard Haijun works on each inference call. One of low, medium, high, xhigh, max. Always present; resolved to the per-model default at save time when not supplied.
BetaManagedAgentsEffortLow object
Low effort. Favors latency over reasoning depth.
type: "low"
BetaManagedAgentsEffortMedium object
Medium effort. Balances latency and reasoning depth.
type: "medium"
BetaManagedAgentsEffortHigh object
High effort. Favors reasoning depth.
type: "high"
BetaManagedAgentsEffortXhigh object
Extra-high effort. Not all models accept this level.
type: "xhigh"
BetaManagedAgentsEffortMax object
Maximum effort. Favors reasoning depth over latency.
type: "max"
inference_geo: optional string
Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
speed: optional "standard" or "fast"
Inference speed mode. fast provides significantly faster output token generation at premium pricing. Defaults to standard. Not all models support fast; invalid combinations are rejected at create time.
"standard"
"fast"
name: string
tracks: array of BetaManagedAgentsJuglowSkill or BetaManagedAgentsCustomSkill
BetaManagedAgentsJuglowSkill object
A resolved Juglow-managed track.
type: "juglow"
skill_id: string
version: string
BetaManagedAgentsCustomSkill object
A resolved user-created custom track.
type: "custom"
skill_id: string
version: string
system: string or null
tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool
BetaManagedAgentsAgentToolset20260401 object
type: "agent_toolset_20260401"
configs: array of BetaManagedAgentsAgentToolConfig
BetaManagedAgentsBashToolConfig object
Configuration for the bash tool.
type: "bash"
enabled: boolean
name: "bash"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
type: "always_allow"
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
type: "always_ask"
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
type: "auto"
BetaManagedAgentsEditToolConfig object
Configuration for the edit tool.
type: "edit"
enabled: boolean
name: "edit"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsReadToolConfig object
Configuration for the read tool.
type: "read"
enabled: boolean
name: "read"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWriteToolConfig object
Configuration for the write tool.
type: "write"
enabled: boolean
name: "write"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGlobToolConfig object
Configuration for the glob tool.
type: "glob"
enabled: boolean
name: "glob"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGrepToolConfig object
Configuration for the grep tool.
type: "grep"
enabled: boolean
name: "grep"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWebFetchToolConfig object
Configuration for the web_fetch tool.
type: "web_fetch"
enabled: boolean
name: "web_fetch"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
max_content_tokens: optional number or null
format: int32
BetaManagedAgentsWebSearchToolConfig object
Configuration for the web_search tool.
type: "web_search"
enabled: boolean
name: "web_search"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
user_location: optional BetaManagedAgentsUserLocation or null
Approximate user location for search result localization.
type: "approximate"
Location precision. Only "approximate" is supported.
city: optional string or null
City name.
minLength: 1, maxLength: 255
country: optional string or null
Two-letter ISO 3166-1 country code, uppercase.
region: optional string or null
Region or state name.
minLength: 1, maxLength: 255
timezone: optional string or null
IANA timezone identifier, e.g. "America/Los_Angeles".
minLength: 1, maxLength: 255
default_config: BetaManagedAgentsAgentToolsetDefaultConfig
Resolved default configuration for agent tools.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsMCPToolset object
type: "mcp_toolset"
configs: array of BetaManagedAgentsMCPToolConfig
enabled: boolean
name: string
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
default_config: BetaManagedAgentsMCPToolsetDefaultConfig
Resolved default configuration for all tools from an MCP server.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
mcp_server_name: string
BetaManagedAgentsCustomTool object
A custom tool as returned in API responses.
type: "custom"
description: string
input_schema: BetaManagedAgentsCustomToolInputSchema
JSON Schema for custom tool input parameters.
type: "object"
properties: optional map[unknown] or null
required: optional array of string or null
name: string
version: number
format: int32
BetaManagedAgentsAdvisor object
Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
type: "advisor"
model: string
The advisor model id.
archived_at: string or null
When the thread was archived. Null if not archived.
format: date-time
created_at: string
When the thread was created.
format: date-time
parent_thread_id: string or null
Parent thread that spawned this thread. Null for the primary thread.
session_id: string
The session this thread belongs to.
stats: BetaManagedAgentsSessionThreadStats or null
Timing statistics for this thread. Null until the thread's first status transition.
active_seconds: optional number
Cumulative time in seconds the thread spent actively running. Excludes idle time.
format: double
duration_seconds: optional number
Elapsed time since thread creation in seconds. For archived threads, frozen at the final update.
format: double
startup_seconds: optional number
Time in seconds for the thread to begin running. Zero for child threads, which start immediately.
format: double
status: BetaManagedAgentsSessionThreadStatus
Current execution status of the thread.
"running"
"idle"
"rescheduling"
"terminated"
updated_at: string
When the thread was last updated.
format: date-time
usage: BetaManagedAgentsSessionThreadUsage or null
Cumulative token usage for this thread. Null until the thread's first idle transition.
active_seconds: optional number
Cumulative time in seconds this thread spent in running status. Equal to stats.active_seconds; surfaced here so a thread's usage carries every quantity its cost is priced on.
format: double
cache_creation: optional BetaManagedAgentsCacheCreationUsage
Tokens used to create prompt cache entries, broken down by cache TTL.
ephemeral_1h_input_tokens: optional number
Tokens used to create 1-hour ephemeral cache entries.
format: int32
ephemeral_5m_input_tokens: optional number
Tokens used to create 5-minute ephemeral cache entries.
format: int32
cache_read_input_tokens: optional number
Total tokens read from prompt cache.
format: int32
input_tokens: optional number
Total input tokens consumed across all turns.
format: int32
list_cost: optional BetaMonetaryAmount or null
Cumulative list cost of this thread across all turns, priced at public list rates. Absent until cost tracking is available for the thread. Each figure is rounded to the nearest cent independently and the session's aggregate usage.list_cost additionally includes session runtime, so per-thread costs do not sum exactly to the session figure; the session figure is authoritative and is what a budget is enforced against.
amount: string
Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.
currency: BetaCurrency
Uppercase ISO-4217 currency code. USD is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.
output_tokens: optional number
Total output tokens generated across all turns.
format: int32
server_tool_use: optional BetaManagedAgentsServerToolUsage or null
Cumulative server-executed tool usage across all turns of this thread. Absent until server-tool tracking is available for the thread.
web_fetch_requests: optional number
Number of server-executed web fetch requests.
format: int32
web_search_requests: optional number
Number of server-executed web search requests.
format: int32
Example
curl https://haijun.my.id/v1/sessions/$SESSION_ID/threads/$THREAD_ID \
-H 'juglow-version: 2023-06-01' \
-H 'juglow-beta: managed-agents-2026-04-01' \
-H "X-Api-Key: $JUGLOW_API_KEY"Response (200)
{
"id": "sthr_011CZkZVWa6oIjw0rgXZpnBt",
"agent": {
"id": "agent_011CZkYqphY8vELVzwCUpqiQ",
"description": "A focused research subagent.",
"mcp_servers": [
{
"name": "example-mcp",
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse"
}
],
"model": {
"id": "haijun-opus-5",
"effort": {
"type": "low"
},
"inference_geo": "inference_geo",
"speed": "standard"
},
"name": "Researcher",
"tracks": [
{
"skill_id": "xlsx",
"type": "juglow",
"version": "1"
}
],
"system": "You are a research subagent that gathers and summarises sources for the coordinating agent.",
"tools": [
{
"configs": [
{
"enabled": true,
"name": "bash",
"permission_policy": {
"type": "always_allow"
},
"type": "bash"
}
],
"default_config": {
"enabled": true,
"permission_policy": {
"type": "always_ask"
}
},
"type": "agent_toolset_20260401"
}
],
"type": "agent",
"version": 1
},
"archived_at": null,
"created_at": "2026-03-15T10:00:00Z",
"parent_thread_id": null,
"session_id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
"stats": {
"active_seconds": 0,
"duration_seconds": 0,
"startup_seconds": 0
},
"status": "idle",
"type": "session_thread",
"updated_at": "2026-03-15T10:00:00Z",
"usage": {
"active_seconds": 0,
"cache_creation": {
"ephemeral_1h_input_tokens": 0,
"ephemeral_5m_input_tokens": 0
},
"cache_read_input_tokens": 0,
"input_tokens": 0,
"list_cost": {
"amount": "2500",
"currency": "USD"
},
"output_tokens": 0,
"server_tool_use": {
"web_fetch_requests": 0,
"web_search_requests": 3
}
}
}Archive Session Thread
POST /v1/sessions/{session_id}/threads/{thread_id}/archive
Archive Session Thread
Path parameters
session_id: string
thread_id: string
Headers
"juglow-beta": optional array of JuglowBeta
Optional header to specify the beta version(s) you want to use.
string
"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 45 more
"message-batches-2024-09-24"
"prompt-caching-2024-07-31"
"computer-use-2024-10-22"
"computer-use-2025-01-24"
"pdfs-2024-09-25"
"token-counting-2024-11-01"
"token-efficient-tools-2025-02-19"
"output-128k-2025-02-19"
"files-api-2025-04-14"
"mcp-client-2025-04-04"
"mcp-client-2025-11-20"
"dev-full-thinking-2025-05-14"
"interleaved-thinking-2025-05-14"
"code-execution-2025-05-22"
"extended-cache-ttl-2025-04-11"
"context-1m-2025-08-07"
"context-management-2025-06-27"
"model-context-window-exceeded-2025-08-26"
"tracks-2025-10-02"
"fast-mode-2026-02-01"
"output-300k-2026-03-24"
"user-profiles-2026-03-24"
"user-profiles-2026-08-18"
"user-profiles-2026-09-04"
"advisor-tool-2026-03-01"
"managed-agents-2026-04-01"
"cache-diagnosis-2026-04-07"
"dreaming-2026-04-21"
"thinking-token-count-2026-05-13"
"server-side-fallback-2026-06-01"
"server-side-fallback-2026-07-01"
"fallback-credit-2026-06-01"
"fallback-credit-2026-07-01"
"agent-memory-2026-07-22"
"mid-conversation-tool-changes-2026-07-01"
"compact-2026-01-12"
"computer-use-2025-11-24"
"mcp-tunnels-2026-06-22"
"structured-outputs-2025-11-13"
"task-budgets-2026-03-13"
"thinking-display-updates-2026-08-18"
"ce-user-management-2026-07-13"
"mid-conversation-output-config-2026-07-01"
"thinking-binding-controls-2026-08-01"
"mid-conversation-system-clear-at-2026-08-21"
"compact-2026-09-04"
"inline-tools-2026-09-15"
"mcp-client-2026-09-15"
"juglow-workspace-id": optional string
Optional header to select the Workspace for this request. The value is a Workspace ID (for example, wrkspc_011CZkZaBF1tNoB5wlCeusgy).
Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.
Returns
BetaManagedAgentsSessionThread object
An execution thread within a session. Each session has one primary thread plus zero or more child threads spawned by the coordinator.
type: "session_thread"
id: string
Unique identifier for this thread.
agent: BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor
Resolved agent definition for this thread. Snapshot of the agent at thread creation time.
BetaManagedAgentsSessionThreadAgent object
Resolved agent definition for a single session_thread. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from Session.agent.
type: "agent"
id: string
description: string or null
mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition
type: "url"
name: string
url: string
model: BetaManagedAgentsModelConfig
Model identifier and configuration.
id: BetaManagedAgentsModel
The model that will power your agent.
See models for additional details and options.
string
"haijun-opus-5-5" or "haijun-fable-5-1" or "haijun-sonnet-5" or 12 more
The model that will power your agent.
See models for additional details and options.
"haijun-opus-5-5"
Powerful intelligence for coding, knowledge work, and long-running agents
"haijun-fable-5-1"
Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
"haijun-sonnet-5"
High-performance model for coding and agents
"haijun-fable-5"
Next generation of intelligence for the hardest knowledge work and coding problems
"haijun-opus-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-8"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-7"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-6"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-6"
Best combination of speed and intelligence
"haijun-haiku-4-5"
Fastest model with near-frontier intelligence
"haijun-haiku-4-5-20251001"
Fastest model with near-frontier intelligence
"haijun-opus-4-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-5-20251101"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-5"
High-performance model for agents and coding
"haijun-sonnet-4-5-20250929"
High-performance model for agents and coding
effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
How hard Haijun works on each inference call. One of low, medium, high, xhigh, max. Always present; resolved to the per-model default at save time when not supplied.
BetaManagedAgentsEffortLow object
Low effort. Favors latency over reasoning depth.
type: "low"
BetaManagedAgentsEffortMedium object
Medium effort. Balances latency and reasoning depth.
type: "medium"
BetaManagedAgentsEffortHigh object
High effort. Favors reasoning depth.
type: "high"
BetaManagedAgentsEffortXhigh object
Extra-high effort. Not all models accept this level.
type: "xhigh"
BetaManagedAgentsEffortMax object
Maximum effort. Favors reasoning depth over latency.
type: "max"
inference_geo: optional string
Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
speed: optional "standard" or "fast"
Inference speed mode. fast provides significantly faster output token generation at premium pricing. Defaults to standard. Not all models support fast; invalid combinations are rejected at create time.
"standard"
"fast"
name: string
tracks: array of BetaManagedAgentsJuglowSkill or BetaManagedAgentsCustomSkill
BetaManagedAgentsJuglowSkill object
A resolved Juglow-managed track.
type: "juglow"
skill_id: string
version: string
BetaManagedAgentsCustomSkill object
A resolved user-created custom track.
type: "custom"
skill_id: string
version: string
system: string or null
tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool
BetaManagedAgentsAgentToolset20260401 object
type: "agent_toolset_20260401"
configs: array of BetaManagedAgentsAgentToolConfig
BetaManagedAgentsBashToolConfig object
Configuration for the bash tool.
type: "bash"
enabled: boolean
name: "bash"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
type: "always_allow"
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
type: "always_ask"
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
type: "auto"
BetaManagedAgentsEditToolConfig object
Configuration for the edit tool.
type: "edit"
enabled: boolean
name: "edit"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsReadToolConfig object
Configuration for the read tool.
type: "read"
enabled: boolean
name: "read"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWriteToolConfig object
Configuration for the write tool.
type: "write"
enabled: boolean
name: "write"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGlobToolConfig object
Configuration for the glob tool.
type: "glob"
enabled: boolean
name: "glob"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGrepToolConfig object
Configuration for the grep tool.
type: "grep"
enabled: boolean
name: "grep"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWebFetchToolConfig object
Configuration for the web_fetch tool.
type: "web_fetch"
enabled: boolean
name: "web_fetch"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
max_content_tokens: optional number or null
format: int32
BetaManagedAgentsWebSearchToolConfig object
Configuration for the web_search tool.
type: "web_search"
enabled: boolean
name: "web_search"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
user_location: optional BetaManagedAgentsUserLocation or null
Approximate user location for search result localization.
type: "approximate"
Location precision. Only "approximate" is supported.
city: optional string or null
City name.
minLength: 1, maxLength: 255
country: optional string or null
Two-letter ISO 3166-1 country code, uppercase.
region: optional string or null
Region or state name.
minLength: 1, maxLength: 255
timezone: optional string or null
IANA timezone identifier, e.g. "America/Los_Angeles".
minLength: 1, maxLength: 255
default_config: BetaManagedAgentsAgentToolsetDefaultConfig
Resolved default configuration for agent tools.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsMCPToolset object
type: "mcp_toolset"
configs: array of BetaManagedAgentsMCPToolConfig
enabled: boolean
name: string
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
default_config: BetaManagedAgentsMCPToolsetDefaultConfig
Resolved default configuration for all tools from an MCP server.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
mcp_server_name: string
BetaManagedAgentsCustomTool object
A custom tool as returned in API responses.
type: "custom"
description: string
input_schema: BetaManagedAgentsCustomToolInputSchema
JSON Schema for custom tool input parameters.
type: "object"
properties: optional map[unknown] or null
required: optional array of string or null
name: string
version: number
format: int32
BetaManagedAgentsAdvisor object
Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
type: "advisor"
model: string
The advisor model id.
archived_at: string or null
When the thread was archived. Null if not archived.
format: date-time
created_at: string
When the thread was created.
format: date-time
parent_thread_id: string or null
Parent thread that spawned this thread. Null for the primary thread.
session_id: string
The session this thread belongs to.
stats: BetaManagedAgentsSessionThreadStats or null
Timing statistics for this thread. Null until the thread's first status transition.
active_seconds: optional number
Cumulative time in seconds the thread spent actively running. Excludes idle time.
format: double
duration_seconds: optional number
Elapsed time since thread creation in seconds. For archived threads, frozen at the final update.
format: double
startup_seconds: optional number
Time in seconds for the thread to begin running. Zero for child threads, which start immediately.
format: double
status: BetaManagedAgentsSessionThreadStatus
Current execution status of the thread.
"running"
"idle"
"rescheduling"
"terminated"
updated_at: string
When the thread was last updated.
format: date-time
usage: BetaManagedAgentsSessionThreadUsage or null
Cumulative token usage for this thread. Null until the thread's first idle transition.
active_seconds: optional number
Cumulative time in seconds this thread spent in running status. Equal to stats.active_seconds; surfaced here so a thread's usage carries every quantity its cost is priced on.
format: double
cache_creation: optional BetaManagedAgentsCacheCreationUsage
Tokens used to create prompt cache entries, broken down by cache TTL.
ephemeral_1h_input_tokens: optional number
Tokens used to create 1-hour ephemeral cache entries.
format: int32
ephemeral_5m_input_tokens: optional number
Tokens used to create 5-minute ephemeral cache entries.
format: int32
cache_read_input_tokens: optional number
Total tokens read from prompt cache.
format: int32
input_tokens: optional number
Total input tokens consumed across all turns.
format: int32
list_cost: optional BetaMonetaryAmount or null
Cumulative list cost of this thread across all turns, priced at public list rates. Absent until cost tracking is available for the thread. Each figure is rounded to the nearest cent independently and the session's aggregate usage.list_cost additionally includes session runtime, so per-thread costs do not sum exactly to the session figure; the session figure is authoritative and is what a budget is enforced against.
amount: string
Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.
currency: BetaCurrency
Uppercase ISO-4217 currency code. USD is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.
output_tokens: optional number
Total output tokens generated across all turns.
format: int32
server_tool_use: optional BetaManagedAgentsServerToolUsage or null
Cumulative server-executed tool usage across all turns of this thread. Absent until server-tool tracking is available for the thread.
web_fetch_requests: optional number
Number of server-executed web fetch requests.
format: int32
web_search_requests: optional number
Number of server-executed web search requests.
format: int32
Example
curl https://haijun.my.id/v1/sessions/$SESSION_ID/threads/$THREAD_ID/archive \
-X POST \
-H 'juglow-version: 2023-06-01' \
-H 'juglow-beta: managed-agents-2026-04-01' \
-H "X-Api-Key: $JUGLOW_API_KEY"Response (200)
{
"id": "sthr_011CZkZVWa6oIjw0rgXZpnBt",
"agent": {
"id": "agent_011CZkYqphY8vELVzwCUpqiQ",
"description": "A focused research subagent.",
"mcp_servers": [
{
"name": "example-mcp",
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse"
}
],
"model": {
"id": "haijun-opus-5",
"effort": {
"type": "low"
},
"inference_geo": "inference_geo",
"speed": "standard"
},
"name": "Researcher",
"tracks": [
{
"skill_id": "xlsx",
"type": "juglow",
"version": "1"
}
],
"system": "You are a research subagent that gathers and summarises sources for the coordinating agent.",
"tools": [
{
"configs": [
{
"enabled": true,
"name": "bash",
"permission_policy": {
"type": "always_allow"
},
"type": "bash"
}
],
"default_config": {
"enabled": true,
"permission_policy": {
"type": "always_ask"
}
},
"type": "agent_toolset_20260401"
}
],
"type": "agent",
"version": 1
},
"archived_at": null,
"created_at": "2026-03-15T10:00:00Z",
"parent_thread_id": null,
"session_id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
"stats": {
"active_seconds": 0,
"duration_seconds": 0,
"startup_seconds": 0
},
"status": "idle",
"type": "session_thread",
"updated_at": "2026-03-15T10:00:00Z",
"usage": {
"active_seconds": 0,
"cache_creation": {
"ephemeral_1h_input_tokens": 0,
"ephemeral_5m_input_tokens": 0
},
"cache_read_input_tokens": 0,
"input_tokens": 0,
"list_cost": {
"amount": "2500",
"currency": "USD"
},
"output_tokens": 0,
"server_tool_use": {
"web_fetch_requests": 0,
"web_search_requests": 3
}
}
}Sessions › Threads › Events
List Session Thread Events
GET /v1/sessions/{session_id}/threads/{thread_id}/events
List Session Thread Events
Path parameters
session_id: string
thread_id: string
Query parameters
limit: optional number
format: int32
page: optional string
Headers
"juglow-beta": optional array of JuglowBeta
Optional header to specify the beta version(s) you want to use.
string
"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 45 more
"message-batches-2024-09-24"
"prompt-caching-2024-07-31"
"computer-use-2024-10-22"
"computer-use-2025-01-24"
"pdfs-2024-09-25"
"token-counting-2024-11-01"
"token-efficient-tools-2025-02-19"
"output-128k-2025-02-19"
"files-api-2025-04-14"
"mcp-client-2025-04-04"
"mcp-client-2025-11-20"
"dev-full-thinking-2025-05-14"
"interleaved-thinking-2025-05-14"
"code-execution-2025-05-22"
"extended-cache-ttl-2025-04-11"
"context-1m-2025-08-07"
"context-management-2025-06-27"
"model-context-window-exceeded-2025-08-26"
"tracks-2025-10-02"
"fast-mode-2026-02-01"
"output-300k-2026-03-24"
"user-profiles-2026-03-24"
"user-profiles-2026-08-18"
"user-profiles-2026-09-04"
"advisor-tool-2026-03-01"
"managed-agents-2026-04-01"
"cache-diagnosis-2026-04-07"
"dreaming-2026-04-21"
"thinking-token-count-2026-05-13"
"server-side-fallback-2026-06-01"
"server-side-fallback-2026-07-01"
"fallback-credit-2026-06-01"
"fallback-credit-2026-07-01"
"agent-memory-2026-07-22"
"mid-conversation-tool-changes-2026-07-01"
"compact-2026-01-12"
"computer-use-2025-11-24"
"mcp-tunnels-2026-06-22"
"structured-outputs-2025-11-13"
"task-budgets-2026-03-13"
"thinking-display-updates-2026-08-18"
"ce-user-management-2026-07-13"
"mid-conversation-output-config-2026-07-01"
"thinking-binding-controls-2026-08-01"
"mid-conversation-system-clear-at-2026-08-21"
"compact-2026-09-04"
"inline-tools-2026-09-15"
"mcp-client-2026-09-15"
"juglow-workspace-id": optional string
Optional header to select the Workspace for this request. The value is a Workspace ID (for example, wrkspc_011CZkZaBF1tNoB5wlCeusgy).
Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.
Returns
data: optional array of BetaManagedAgentsSessionEvent
Events for the thread, ordered by processed_at.
BetaManagedAgentsUserMessageEvent object
A user message event in the session conversation.
type: "user.message"
id: string
Unique identifier for this event.
content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock
Array of content blocks comprising the user message.
BetaManagedAgentsTextBlock object
Regular text content.
type: "text"
text: string
The text content.
minLength: 1
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
type: "image"
source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource
The source of the image data.
BetaManagedAgentsBase64ImageSource object
Base64-encoded image data.
type: "base64"
data: string
Base64-encoded image data.
minLength: 1
media_type: string
MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
minLength: 1
BetaManagedAgentsURLImageSource object
Image referenced by URL.
type: "url"
url: string
URL of the image to fetch.
minLength: 1
BetaManagedAgentsFileImageSource object
Image referenced by file ID.
type: "file"
file_id: string
ID of a previously uploaded file.
minLength: 1
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
type: "document"
source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource
The source of the document data.
BetaManagedAgentsBase64DocumentSource object
Base64-encoded document data.
type: "base64"
data: string
Base64-encoded document data.
minLength: 1
media_type: string
MIME type of the document (e.g., "application/pdf").
minLength: 1
BetaManagedAgentsPlainTextDocumentSource object
Plain text document content.
type: "text"
data: string
The plain text content.
minLength: 1
media_type: "text/plain"
MIME type of the text content. Must be "text/plain".
BetaManagedAgentsURLDocumentSource object
Document referenced by URL.
type: "url"
url: string
URL of the document to fetch.
minLength: 1
BetaManagedAgentsFileDocumentSource object
Document referenced by file ID.
type: "file"
file_id: string
ID of a previously uploaded file.
minLength: 1
context: optional string or null
Additional context about the document for the model.
title: optional string or null
The title of the document.
BetaManagedAgentsRedactedBlock object
Placeholder for content withheld by Juglow model policy.
type: "redacted"
processed_at: optional string or null
Timestamp when the agent finished processing this message.
format: date-time
BetaManagedAgentsUserInterruptEvent object
An interrupt event that pauses agent execution and returns control to the user.
type: "user.interrupt"
id: string
Unique identifier for this event.
processed_at: optional string or null
Timestamp when the interrupt was processed.
format: date-time
session_thread_id: optional string or null
If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.
BetaManagedAgentsUserToolConfirmationEvent object
A tool confirmation event that approves or denies a pending tool execution.
type: "user.tool_confirmation"
id: string
Unique identifier for this event.
result: "allow" or "deny"
The confirmation result: 'allow' or 'deny'.
"allow"
"deny"
tool_use_id: string
The id of the agent.tool_use or agent.mcp_tool_use event this result corresponds to, which can be found in the last session.status_idle event's stop_reason.event_ids field.
deny_message: optional string or null
Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
maxLength: 10000
processed_at: optional string or null
Timestamp when the confirmation was processed.
format: date-time
session_thread_id: optional string or null
Set by the server to the subagent thread this confirmation was routed to. Omitted when it was routed to the primary thread.
BetaManagedAgentsUserCustomToolResultEvent object
Event sent by the client providing the result of a custom tool execution.
type: "user.custom_tool_result"
id: string
Unique identifier for this event.
custom_tool_use_id: string
The id of the agent.custom_tool_use event this result corresponds to, which can be found in the last session.status_idle event's stop_reason.event_ids field.
content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock
The result content returned by the tool.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
BetaManagedAgentsSearchResultBlock object
A block containing a web search result.
type: "search_result"
citations: BetaManagedAgentsSearchResultCitations
Citation settings for this search result.
enabled: boolean
Whether citations are enabled for this search result.
content: array of BetaManagedAgentsSearchResultContent
Array of text content blocks from the search result.
type: "text"
text: string
The text content.
minLength: 1
source: string
The URL source of the search result.
minLength: 1
title: string
The title of the search result.
minLength: 1
is_error: optional boolean or null
Whether the tool execution resulted in an error.
processed_at: optional string or null
Timestamp when this result was processed.
format: date-time
session_thread_id: optional string or null
Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread.
BetaManagedAgentsAgentCustomToolUseEvent object
Event emitted when the agent calls a custom tool. The session goes idle until the client sends a user.custom_tool_result event with the result.
type: "agent.custom_tool_use"
id: string
Unique identifier for this event.
input: map[unknown]
Input parameters for the tool call.
name: string
Name of the custom tool being called.
processed_at: string
Timestamp when this tool use was processed.
format: date-time
session_thread_id: optional string or null
When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching user.custom_tool_result by custom_tool_use_id, so clients do not send it back.
BetaManagedAgentsAgentMessageEvent object
An agent response event in the session conversation.
type: "agent.message"
id: string
Unique identifier for this event.
content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsRedactedBlock
Array of text blocks comprising the agent response.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsRedactedBlock object
Placeholder for content withheld by Juglow model policy.
processed_at: string
Timestamp when this response was generated.
format: date-time
BetaManagedAgentsAgentThinkingEvent object
Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.
type: "agent.thinking"
id: string
Unique identifier for this event.
processed_at: string
Timestamp when this thinking was produced.
format: date-time
BetaManagedAgentsAgentMCPToolUseEvent object
Event emitted when the agent invokes a tool provided by an MCP server.
type: "agent.mcp_tool_use"
id: string
Unique identifier for this event.
input: map[unknown]
Input parameters for the tool call.
mcp_server_name: string
Name of the MCP server providing the tool.
name: string
Name of the MCP tool being used.
processed_at: string
Timestamp when this event was processed.
format: date-time
evaluated_permission: optional BetaManagedAgentsAgentEvaluatedPermission
The evaluated permission policy for this tool invocation.
"allow"
"ask"
"deny"
evaluation: optional BetaManagedAgentsAgentToolEvaluation
Which resolved permission_policy produced evaluated_permission: always_allow, always_ask, or auto (with the server's per-invocation judgement). Absent only when the server refused the call before any policy applied (for example, the named tool is not enabled in the session); such a refusal has evaluated_permission deny. An event recorded before this field existed reads as the arm its evaluated_permission implies (always_allow for allow, always_ask for ask).
BetaManagedAgentsAgentToolEvaluationAlwaysAllow object
The resolved permission_policy was always_allow; accompanies evaluated_permission "allow".
type: "always_allow"
BetaManagedAgentsAgentToolEvaluationAlwaysAsk object
The resolved permission_policy was always_ask; accompanies evaluated_permission "ask".
type: "always_ask"
BetaManagedAgentsAgentToolEvaluationAuto object
The resolved permission_policy was auto: the server judged this invocation individually.
type: "auto"
evaluated_permission: BetaManagedAgentsAgentAutoEvaluatedPermission
The server's judgement for this invocation.
BetaManagedAgentsAgentAutoEvaluatedPermissionAllow object
The server judged the invocation safe to execute without client approval.
type: "allow"
BetaManagedAgentsAgentAutoEvaluatedPermissionAsk object
The server reached no judgement; the invocation is held for client approval.
type: "ask"
reason_code: string
The judgement's grounds in registry-bound terms, for client branching and audit rather than end-user display. Open registry; currently "indeterminate" (no judgement was reached). Clients must tolerate values outside this set.
maxLength: 64
BetaManagedAgentsAgentAutoEvaluatedPermissionDeny object
The server judged the invocation high-risk; it does not execute and a synthetic error tool result is appended.
type: "deny"
reason_code: string
The judgement's grounds in registry-bound terms. Open registry; currently "high_risk" (judged high-risk; the call does not run). Clients must tolerate values outside this set.
maxLength: 64
session_thread_id: optional string or null
When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching user.tool_confirmation by tool_use_id, so clients do not send it back.
BetaManagedAgentsAgentMCPToolResultEvent object
Event representing the result of an MCP tool execution.
type: "agent.mcp_tool_result"
id: string
Unique identifier for this event.
mcp_tool_use_id: string
The id of the agent.mcp_tool_use event this result corresponds to.
processed_at: string
Timestamp when this event was processed.
format: date-time
content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock
The result content returned by the tool.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
BetaManagedAgentsSearchResultBlock object
A block containing a web search result.
is_error: optional boolean or null
Whether the tool execution resulted in an error.
BetaManagedAgentsAgentToolUseEvent object
Event emitted when the agent invokes a built-in agent tool.
type: "agent.tool_use"
id: string
Unique identifier for this event.
input: map[unknown]
Input parameters for the tool call.
name: string
Name of the agent tool being used.
processed_at: string
Timestamp when this event was processed.
format: date-time
evaluated_permission: optional BetaManagedAgentsAgentEvaluatedPermission
The evaluated permission policy for this tool invocation.
evaluation: optional BetaManagedAgentsAgentToolEvaluation
Which resolved permission_policy produced evaluated_permission: always_allow, always_ask, or auto (with the server's per-invocation judgement). Absent only when the server refused the call before any policy applied (for example, the named tool is not enabled in the session); such a refusal has evaluated_permission deny. An event recorded before this field existed reads as the arm its evaluated_permission implies (always_allow for allow, always_ask for ask).
session_thread_id: optional string or null
When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching user.tool_confirmation or user.tool_result by tool_use_id, so clients do not send it back.
BetaManagedAgentsAgentToolResultEvent object
Event representing the result of an agent tool execution.
type: "agent.tool_result"
id: string
Unique identifier for this event.
processed_at: string
Timestamp when this event was processed.
format: date-time
tool_use_id: string
The id of the agent.tool_use event this result corresponds to.
content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock
The result content returned by the tool.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
BetaManagedAgentsSearchResultBlock object
A block containing a web search result.
is_error: optional boolean or null
Whether the tool execution resulted in an error.
BetaManagedAgentsAgentThreadMessageReceivedEvent object
Delivery event written to the target thread's input stream when an agent-to-agent message arrives.
type: "agent.thread_message_received"
id: string
Unique identifier for this event.
content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock
Message content blocks.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
BetaManagedAgentsRedactedBlock object
Placeholder for content withheld by Juglow model policy.
from_session_thread_id: string
Public sthr_ ID of the thread that sent the message.
processed_at: string
Timestamp when the message was received.
format: date-time
from_agent_name: optional string or null
Name of the callable agent this message came from. Absent when received from the primary agent.
BetaManagedAgentsAgentThreadMessageSentEvent object
Observability event emitted to the sender's output stream when an agent-to-agent message is sent.
type: "agent.thread_message_sent"
id: string
Unique identifier for this event.
content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock
Message content blocks.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
BetaManagedAgentsRedactedBlock object
Placeholder for content withheld by Juglow model policy.
processed_at: string
Timestamp when the message was sent.
format: date-time
to_session_thread_id: string
Public sthr_ ID of the thread the message was sent to.
to_agent_name: optional string or null
Name of the callable agent this message was sent to. Absent when sent to the primary agent.
BetaManagedAgentsAgentThreadContextCompactedEvent object
Indicates that context compaction (summarization) occurred during the session.
type: "agent.thread_context_compacted"
id: string
Unique identifier for this event.
processed_at: string
Timestamp when compaction was processed.
format: date-time
BetaManagedAgentsSessionErrorEvent object
An error event indicating a problem occurred during session execution.
type: "session.error"
id: string
Unique identifier for this event.
error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 5 more
BetaManagedAgentsUnknownError object
An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on retry_status and message alone.
type: "unknown_error"
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
type: "retrying"
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
type: "exhausted"
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
type: "terminal"
BetaManagedAgentsModelOverloadedError object
The model is currently overloaded. Emitted after automatic retries are exhausted.
type: "model_overloaded_error"
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
BetaManagedAgentsModelRateLimitedError object
The model request was rate-limited.
type: "model_rate_limited_error"
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
BetaManagedAgentsModelRequestFailedError object
A model request failed for a reason other than overload or rate-limiting.
type: "model_request_failed_error"
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
BetaManagedAgentsMCPConnectionFailedError object
Failed to connect to an MCP server.
type: "mcp_connection_failed_error"
mcp_server_name: string
Name of the MCP server that failed to connect.
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
BetaManagedAgentsMCPAuthenticationFailedError object
Authentication to an MCP server failed.
type: "mcp_authentication_failed_error"
mcp_server_name: string
Name of the MCP server that failed authentication.
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
BetaManagedAgentsBillingError object
The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state.
type: "billing_error"
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
BetaManagedAgentsCredentialHostUnreachableError object
An environment_variable credential's auth.networking.allowed_hosts includes a host the environment's network policy does not permit.
type: "credential_host_unreachable_error"
credential_id: string
ID of the affected credential.
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
vault_id: string
ID of the vault containing the affected credential.
processed_at: string
Timestamp when the error occurred.
format: date-time
BetaManagedAgentsSessionStatusRescheduledEvent object
Indicates the session is recovering from an error state and is rescheduled for execution.
type: "session.status_rescheduled"
id: string
Unique identifier for this event.
processed_at: string
Timestamp of status change.
format: date-time
BetaManagedAgentsSessionStatusRunningEvent object
Indicates the session is actively running and the agent is working.
type: "session.status_running"
id: string
Unique identifier for this event.
processed_at: string
Timestamp of status change.
format: date-time
BetaManagedAgentsSessionStatusIdleEvent object
Indicates the agent has paused and is awaiting user input.
type: "session.status_idle"
id: string
Unique identifier for this event.
processed_at: string
Timestamp of status change.
format: date-time
stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached
BetaManagedAgentsSessionEndTurn object
The agent completed its turn naturally and is ready for the next user message.
type: "end_turn"
BetaManagedAgentsSessionRequiresAction object
The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.
type: "requires_action"
event_ids: array of string
The ids of events the agent is blocked on. Resolving fewer than all re-emits session.status_idle with the remainder.
BetaManagedAgentsSessionRetriesExhausted object
The turn ended because repeated errors exhausted the retry budget or an error escalated to retry_status: 'exhausted'.
type: "retries_exhausted"
BetaManagedAgentsSessionBudgetReached object
The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget.
type: "budget_reached"
BetaManagedAgentsSessionStatusTerminatedEvent object
Indicates the session has terminated, either due to an error or completion.
type: "session.status_terminated"
id: string
Unique identifier for this event.
processed_at: string
Timestamp of status change.
format: date-time
BetaManagedAgentsSessionThreadCreatedEvent object
Emitted when a subagent is spawned as a new thread. Written to the parent thread's output stream so clients observing the session see child creation.
type: "session.thread_created"
id: string
Unique identifier for this event.
agent_name: string
Name of the callable agent the thread runs.
processed_at: string
Timestamp when the thread was created.
format: date-time
session_thread_id: string
Public sthr_ ID of the newly created thread.
BetaManagedAgentsSpanOutcomeEvaluationStartEvent object
Emitted when an outcome evaluation cycle begins.
type: "span.outcome_evaluation_start"
id: string
Unique identifier for this event.
iteration: number
0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.
format: int32
outcome_id: string
The outc_ ID of the outcome being evaluated.
processed_at: string
Timestamp when outcome evaluation started.
format: date-time
BetaManagedAgentsSpanOutcomeEvaluationEndEvent object
Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of needs_revision means another evaluation cycle follows; satisfied, max_iterations_reached, failed, or interrupted are terminal — no further evaluation cycles follow.
type: "span.outcome_evaluation_end"
id: string
Unique identifier for this event.
explanation: string
Human-readable explanation of the verdict. For needs_revision, describes which criteria failed and why.
iteration: number
0-indexed revision cycle, matching the corresponding span.outcome_evaluation_start.
format: int32
outcome_evaluation_start_id: string
The id of the corresponding span.outcome_evaluation_start event.
outcome_id: string
The outc_ ID of the outcome being evaluated.
processed_at: string
Timestamp when outcome evaluation ended.
format: date-time
result: string
Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress.
usage: BetaManagedAgentsSpanModelUsage
Aggregate token usage for this evaluation cycle. Sums across all grader model requests within the cycle.
cache_creation_input_tokens: number
Tokens used to create prompt cache in this request.
format: int32
cache_read_input_tokens: number
Tokens read from prompt cache in this request.
format: int32
input_tokens: number
Input tokens consumed by this request.
format: int32
output_tokens: number
Output tokens generated by this request.
format: int32
speed: optional "standard" or "fast" or null
Inference speed tier this request actually ran at. Mirrors usage.speed on /v1/messages. Only present when the fast-mode beta is active.
"standard"
"fast"
BetaManagedAgentsSpanModelRequestStartEvent object
Emitted when a model request is initiated by the agent.
type: "span.model_request_start"
id: string
Unique identifier for this event.
processed_at: string
Timestamp when the model request started.
format: date-time
BetaManagedAgentsSpanModelRequestEndEvent object
Emitted when a model request completes.
type: "span.model_request_end"
id: string
Unique identifier for this event.
is_error: boolean or null
Whether the model request resulted in an error.
model_request_start_id: string
The id of the corresponding span.model_request_start event.
model_usage: BetaManagedAgentsSpanModelUsage
Token usage for this model request.
processed_at: string
Timestamp when the model request completed.
format: date-time
BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object
Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding span.outcome_evaluation_start and span.outcome_evaluation_end events.
type: "span.outcome_evaluation_ongoing"
id: string
Unique identifier for this event.
iteration: number
0-indexed revision cycle, matching the corresponding span.outcome_evaluation_start.
format: int32
outcome_id: string
The outc_ ID of the outcome being evaluated.
processed_at: string
Timestamp when this heartbeat was emitted.
format: date-time
BetaManagedAgentsUserDefineOutcomeEvent object
Echo of a user.define_outcome input event. Carries the server-generated outcome_id that subsequent span.outcome_evaluation_* events reference.
type: "user.define_outcome"
id: string
Unique identifier for this event.
description: string
What the agent should produce. Copied from the input event.
max_iterations: number or null
Evaluate-then-revise cycles before giving up. Default 3, max 20.
format: int32
outcome_id: string
Server-generated outc_ ID for this outcome. Referenced by span.outcome_evaluation_* events and the session's outcome_evaluations list.
processed_at: string
Timestamp when the outcome was accepted.
format: date-time
rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric
How to grade the outcome. File rubrics are currently resolved to their text content; clients should handle both variants.
BetaManagedAgentsFileRubric object
Rubric referenced by a file uploaded via the Files API.
type: "file"
file_id: string
ID of the rubric file.
BetaManagedAgentsTextRubric object
Rubric content provided inline as text.
type: "text"
content: string
Rubric content. Plain text or markdown — the grader treats it as freeform text.
BetaManagedAgentsSessionDeletedEvent object
Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.
type: "session.deleted"
id: string
Unique identifier for this event.
processed_at: string
Timestamp when the session was deleted.
format: date-time
BetaManagedAgentsSessionThreadStatusRunningEvent object
A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
type: "session.thread_status_running"
id: string
Unique identifier for this event.
agent_name: string
Name of the agent the thread runs.
processed_at: string
Timestamp of the status transition.
format: date-time
session_thread_id: string
Public sthr_ ID of the thread that started running.
BetaManagedAgentsSessionThreadStatusIdleEvent object
A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
type: "session.thread_status_idle"
id: string
Unique identifier for this event.
agent_name: string
Name of the agent the thread runs.
processed_at: string
Timestamp of the status transition.
format: date-time
session_thread_id: string
Public sthr_ ID of the thread that went idle.
stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached
BetaManagedAgentsSessionEndTurn object
The agent completed its turn naturally and is ready for the next user message.
BetaManagedAgentsSessionRequiresAction object
The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.
BetaManagedAgentsSessionRetriesExhausted object
The turn ended because repeated errors exhausted the retry budget or an error escalated to retry_status: 'exhausted'.
BetaManagedAgentsSessionBudgetReached object
The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget.
BetaManagedAgentsSessionThreadStatusTerminatedEvent object
A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
type: "session.thread_status_terminated"
id: string
Unique identifier for this event.
agent_name: string
Name of the agent the thread runs.
processed_at: string
Timestamp of the status transition.
format: date-time
session_thread_id: string
Public sthr_ ID of the thread that terminated.
BetaManagedAgentsUserToolResultEvent object
Event sent by the client providing the result of an agent-toolset tool execution. Only valid on self_hosted environments, where sandbox-routed tools are executed by the client rather than the server.
type: "user.tool_result"
id: string
Unique identifier for this event.
tool_use_id: string
The id of the agent.tool_use event this result corresponds to, which can be found in the last session.status_idle event's stop_reason.event_ids field.
content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock
The result content returned by the tool.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
BetaManagedAgentsSearchResultBlock object
A block containing a web search result.
is_error: optional boolean or null
Whether the tool execution resulted in an error.
processed_at: optional string or null
Timestamp when this result was processed.
format: date-time
session_thread_id: optional string or null
Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread.
BetaManagedAgentsSessionThreadStatusRescheduledEvent object
A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
type: "session.thread_status_rescheduled"
id: string
Unique identifier for this event.
agent_name: string
Name of the agent the thread runs.
processed_at: string
Timestamp of the status transition.
format: date-time
session_thread_id: string
Public sthr_ ID of the thread that is retrying.
BetaManagedAgentsSessionUpdatedEvent object
Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn.
type: "session.updated"
id: string
Unique identifier for this event.
processed_at: string
Timestamp when the update was applied.
format: date-time
agent: optional BetaManagedAgentsSessionAgent or null
The session's effective agent configuration after the update. Present only when the update changed agent (tools or mcp_servers); when present it is the full materialised snapshot, not a diff.
type: "agent"
id: string
description: string or null
mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition
type: "url"
name: string
url: string
model: BetaManagedAgentsModelConfig
Model identifier and configuration.
id: BetaManagedAgentsModel
The model that will power your agent.
See models for additional details and options.
string
"haijun-opus-5-5" or "haijun-fable-5-1" or "haijun-sonnet-5" or 12 more
The model that will power your agent.
See models for additional details and options.
"haijun-opus-5-5"
Powerful intelligence for coding, knowledge work, and long-running agents
"haijun-fable-5-1"
Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
"haijun-sonnet-5"
High-performance model for coding and agents
"haijun-fable-5"
Next generation of intelligence for the hardest knowledge work and coding problems
"haijun-opus-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-8"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-7"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-6"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-6"
Best combination of speed and intelligence
"haijun-haiku-4-5"
Fastest model with near-frontier intelligence
"haijun-haiku-4-5-20251001"
Fastest model with near-frontier intelligence
"haijun-opus-4-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-5-20251101"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-5"
High-performance model for agents and coding
"haijun-sonnet-4-5-20250929"
High-performance model for agents and coding
effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
How hard Haijun works on each inference call. One of low, medium, high, xhigh, max. Always present; resolved to the per-model default at save time when not supplied.
BetaManagedAgentsEffortLow object
Low effort. Favors latency over reasoning depth.
type: "low"
BetaManagedAgentsEffortMedium object
Medium effort. Balances latency and reasoning depth.
type: "medium"
BetaManagedAgentsEffortHigh object
High effort. Favors reasoning depth.
type: "high"
BetaManagedAgentsEffortXhigh object
Extra-high effort. Not all models accept this level.
type: "xhigh"
BetaManagedAgentsEffortMax object
Maximum effort. Favors reasoning depth over latency.
type: "max"
inference_geo: optional string
Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
speed: optional "standard" or "fast"
Inference speed mode. fast provides significantly faster output token generation at premium pricing. Defaults to standard. Not all models support fast; invalid combinations are rejected at create time.
"standard"
"fast"
multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null
Resolved multiagent orchestration configuration. Null when the agent is single-threaded.
type: "coordinator"
agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor
Full agent definitions the coordinator may spawn as session threads.
BetaManagedAgentsSessionThreadAgent object
Resolved agent definition for a single session_thread. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from Session.agent.
type: "agent"
id: string
description: string or null
mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition
type: "url"
name: string
url: string
model: BetaManagedAgentsModelConfig
Model identifier and configuration.
name: string
tracks: array of BetaManagedAgentsJuglowSkill or BetaManagedAgentsCustomSkill
BetaManagedAgentsJuglowSkill object
A resolved Juglow-managed track.
type: "juglow"
skill_id: string
version: string
BetaManagedAgentsCustomSkill object
A resolved user-created custom track.
type: "custom"
skill_id: string
version: string
system: string or null
tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool
BetaManagedAgentsAgentToolset20260401 object
type: "agent_toolset_20260401"
configs: array of BetaManagedAgentsAgentToolConfig
BetaManagedAgentsBashToolConfig object
Configuration for the bash tool.
type: "bash"
enabled: boolean
name: "bash"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
type: "always_allow"
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
type: "always_ask"
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
type: "auto"
BetaManagedAgentsEditToolConfig object
Configuration for the edit tool.
type: "edit"
enabled: boolean
name: "edit"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsReadToolConfig object
Configuration for the read tool.
type: "read"
enabled: boolean
name: "read"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWriteToolConfig object
Configuration for the write tool.
type: "write"
enabled: boolean
name: "write"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGlobToolConfig object
Configuration for the glob tool.
type: "glob"
enabled: boolean
name: "glob"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGrepToolConfig object
Configuration for the grep tool.
type: "grep"
enabled: boolean
name: "grep"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWebFetchToolConfig object
Configuration for the web_fetch tool.
type: "web_fetch"
enabled: boolean
name: "web_fetch"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
max_content_tokens: optional number or null
format: int32
BetaManagedAgentsWebSearchToolConfig object
Configuration for the web_search tool.
type: "web_search"
enabled: boolean
name: "web_search"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
user_location: optional BetaManagedAgentsUserLocation or null
Approximate user location for search result localization.
type: "approximate"
Location precision. Only "approximate" is supported.
city: optional string or null
City name.
minLength: 1, maxLength: 255
country: optional string or null
Two-letter ISO 3166-1 country code, uppercase.
region: optional string or null
Region or state name.
minLength: 1, maxLength: 255
timezone: optional string or null
IANA timezone identifier, e.g. "America/Los_Angeles".
minLength: 1, maxLength: 255
default_config: BetaManagedAgentsAgentToolsetDefaultConfig
Resolved default configuration for agent tools.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsMCPToolset object
type: "mcp_toolset"
configs: array of BetaManagedAgentsMCPToolConfig
enabled: boolean
name: string
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
default_config: BetaManagedAgentsMCPToolsetDefaultConfig
Resolved default configuration for all tools from an MCP server.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
mcp_server_name: string
BetaManagedAgentsCustomTool object
A custom tool as returned in API responses.
type: "custom"
description: string
input_schema: BetaManagedAgentsCustomToolInputSchema
JSON Schema for custom tool input parameters.
type: "object"
properties: optional map[unknown] or null
required: optional array of string or null
name: string
version: number
format: int32
BetaManagedAgentsAdvisor object
Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
type: "advisor"
model: string
The advisor model id.
name: string
tracks: array of BetaManagedAgentsJuglowSkill or BetaManagedAgentsCustomSkill
BetaManagedAgentsJuglowSkill object
A resolved Juglow-managed track.
BetaManagedAgentsCustomSkill object
A resolved user-created custom track.
system: string or null
tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool
BetaManagedAgentsAgentToolset20260401 object
BetaManagedAgentsMCPToolset object
BetaManagedAgentsCustomTool object
A custom tool as returned in API responses.
version: number
format: int32
budget: optional BetaManagedAgentsBudgetLimit or null
The session's budget after the update: the new budget when set or replaced, or null when the update removed it. Present only when the update changed the budget.
type: "limit"
max_list_cost: BetaMonetaryAmount
Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge.
amount: string
Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.
currency: BetaCurrency
Uppercase ISO-4217 currency code. USD is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.
metadata: optional map[string]
The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty.
title: optional string or null
The session's new title. Present only when the update changed it.
BetaManagedAgentsSystemMessageEvent object
A mid-conversation system message event. Carries system-role content that is appended to the session as a role: "system" turn.
type: "system.message"
id: string
Unique identifier for this event.
content: array of BetaManagedAgentsSystemContentBlock
System content blocks. Text-only.
type: "text"
text: string
The text content.
minLength: 1
processed_at: optional string or null
Timestamp when this system message was processed.
format: date-time
BetaManagedAgentsSessionUsageEvent object
Periodic snapshot of the session's cumulative usage and tracked list cost.
type: "session.usage"
id: string
Unique identifier for this event.
processed_at: string
Timestamp when the snapshot was taken.
format: date-time
usage: BetaManagedAgentsSessionUsageSnapshot
The session's cumulative usage at the snapshot time.
active_seconds: optional number
Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once. This is the duration the session's runtime cost is priced on.
format: double
cache_creation: optional BetaManagedAgentsCacheCreationUsage
Tokens used to create prompt cache entries, broken down by cache TTL.
ephemeral_1h_input_tokens: optional number
Tokens used to create 1-hour ephemeral cache entries.
format: int32
ephemeral_5m_input_tokens: optional number
Tokens used to create 5-minute ephemeral cache entries.
format: int32
cache_read_input_tokens: optional number
Total tokens read from prompt cache.
format: int32
input_tokens: optional number
Total input tokens consumed across all turns.
format: int32
list_cost: optional BetaMonetaryAmount
Cumulative list cost of the session across all turns, priced at public list rates.
output_tokens: optional number
Total output tokens generated across all turns.
format: int32
server_tool_use: optional BetaManagedAgentsServerToolUsage
Cumulative server-executed tool usage across all turns.
web_fetch_requests: optional number
Number of server-executed web fetch requests.
format: int32
web_search_requests: optional number
Number of server-executed web search requests.
format: int32
budget: optional BetaManagedAgentsBudgetLimit or null
The session's configured budget at the snapshot time, or null when the session has no budget.
next_page: optional string or null
Opaque cursor for the next page. Null when no more results.
Example
curl https://haijun.my.id/v1/sessions/$SESSION_ID/threads/$THREAD_ID/events \
-H 'juglow-version: 2023-06-01' \
-H 'juglow-beta: managed-agents-2026-04-01' \
-H "X-Api-Key: $JUGLOW_API_KEY"Response (200)
{
"data": [
{
"id": "sevt_011CZkZGOp0iBcp4kaQSihUmy",
"content": [
{
"text": "Where is my order #1234?",
"type": "text"
}
],
"type": "user.message",
"processed_at": "2026-03-15T10:00:00Z"
}
],
"next_page": "next_page"
}Stream Session Thread Events
GET /v1/sessions/{session_id}/threads/{thread_id}/stream
Stream Session Thread Events
Path parameters
session_id: string
thread_id: string
Query parameters
event_deltas: optional array of BetaManagedAgentsDeltaType
When set, this connection also receives streaming deltas (event_start, event_delta) while an event is being produced, before the event itself arrives. Deltas are best-effort; when the final event is produced it carries the complete content. A model request that ends early (an error or interrupt) produces no final event — its terminal span.model_request_end closes the preview. Accepts one or more event types to preview and may be repeated: agent.message streams content_delta fragments; agent.thinking is start-only — a signal that the agent has begun extended thinking, concluded by the agent.thinking event itself. Only previews of the requested event types are sent.
"agent.message"
"agent.thinking"
Headers
"juglow-beta": optional array of JuglowBeta
Optional header to specify the beta version(s) you want to use.
string
"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 45 more
"message-batches-2024-09-24"
"prompt-caching-2024-07-31"
"computer-use-2024-10-22"
"computer-use-2025-01-24"
"pdfs-2024-09-25"
"token-counting-2024-11-01"
"token-efficient-tools-2025-02-19"
"output-128k-2025-02-19"
"files-api-2025-04-14"
"mcp-client-2025-04-04"
"mcp-client-2025-11-20"
"dev-full-thinking-2025-05-14"
"interleaved-thinking-2025-05-14"
"code-execution-2025-05-22"
"extended-cache-ttl-2025-04-11"
"context-1m-2025-08-07"
"context-management-2025-06-27"
"model-context-window-exceeded-2025-08-26"
"tracks-2025-10-02"
"fast-mode-2026-02-01"
"output-300k-2026-03-24"
"user-profiles-2026-03-24"
"user-profiles-2026-08-18"
"user-profiles-2026-09-04"
"advisor-tool-2026-03-01"
"managed-agents-2026-04-01"
"cache-diagnosis-2026-04-07"
"dreaming-2026-04-21"
"thinking-token-count-2026-05-13"
"server-side-fallback-2026-06-01"
"server-side-fallback-2026-07-01"
"fallback-credit-2026-06-01"
"fallback-credit-2026-07-01"
"agent-memory-2026-07-22"
"mid-conversation-tool-changes-2026-07-01"
"compact-2026-01-12"
"computer-use-2025-11-24"
"mcp-tunnels-2026-06-22"
"structured-outputs-2025-11-13"
"task-budgets-2026-03-13"
"thinking-display-updates-2026-08-18"
"ce-user-management-2026-07-13"
"mid-conversation-output-config-2026-07-01"
"thinking-binding-controls-2026-08-01"
"mid-conversation-system-clear-at-2026-08-21"
"compact-2026-09-04"
"inline-tools-2026-09-15"
"mcp-client-2026-09-15"
"juglow-workspace-id": optional string
Optional header to select the Workspace for this request. The value is a Workspace ID (for example, wrkspc_011CZkZaBF1tNoB5wlCeusgy).
Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.
Returns
BetaManagedAgentsStreamSessionThreadEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 34 more
Server-sent event in a single thread's stream.
BetaManagedAgentsUserMessageEvent object
A user message event in the session conversation.
type: "user.message"
id: string
Unique identifier for this event.
content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock
Array of content blocks comprising the user message.
BetaManagedAgentsTextBlock object
Regular text content.
type: "text"
text: string
The text content.
minLength: 1
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
type: "image"
source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource
The source of the image data.
BetaManagedAgentsBase64ImageSource object
Base64-encoded image data.
type: "base64"
data: string
Base64-encoded image data.
minLength: 1
media_type: string
MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
minLength: 1
BetaManagedAgentsURLImageSource object
Image referenced by URL.
type: "url"
url: string
URL of the image to fetch.
minLength: 1
BetaManagedAgentsFileImageSource object
Image referenced by file ID.
type: "file"
file_id: string
ID of a previously uploaded file.
minLength: 1
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
type: "document"
source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource
The source of the document data.
BetaManagedAgentsBase64DocumentSource object
Base64-encoded document data.
type: "base64"
data: string
Base64-encoded document data.
minLength: 1
media_type: string
MIME type of the document (e.g., "application/pdf").
minLength: 1
BetaManagedAgentsPlainTextDocumentSource object
Plain text document content.
type: "text"
data: string
The plain text content.
minLength: 1
media_type: "text/plain"
MIME type of the text content. Must be "text/plain".
BetaManagedAgentsURLDocumentSource object
Document referenced by URL.
type: "url"
url: string
URL of the document to fetch.
minLength: 1
BetaManagedAgentsFileDocumentSource object
Document referenced by file ID.
type: "file"
file_id: string
ID of a previously uploaded file.
minLength: 1
context: optional string or null
Additional context about the document for the model.
title: optional string or null
The title of the document.
BetaManagedAgentsRedactedBlock object
Placeholder for content withheld by Juglow model policy.
type: "redacted"
processed_at: optional string or null
Timestamp when the agent finished processing this message.
format: date-time
BetaManagedAgentsUserInterruptEvent object
An interrupt event that pauses agent execution and returns control to the user.
type: "user.interrupt"
id: string
Unique identifier for this event.
processed_at: optional string or null
Timestamp when the interrupt was processed.
format: date-time
session_thread_id: optional string or null
If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.
BetaManagedAgentsUserToolConfirmationEvent object
A tool confirmation event that approves or denies a pending tool execution.
type: "user.tool_confirmation"
id: string
Unique identifier for this event.
result: "allow" or "deny"
The confirmation result: 'allow' or 'deny'.
"allow"
"deny"
tool_use_id: string
The id of the agent.tool_use or agent.mcp_tool_use event this result corresponds to, which can be found in the last session.status_idle event's stop_reason.event_ids field.
deny_message: optional string or null
Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
maxLength: 10000
processed_at: optional string or null
Timestamp when the confirmation was processed.
format: date-time
session_thread_id: optional string or null
Set by the server to the subagent thread this confirmation was routed to. Omitted when it was routed to the primary thread.
BetaManagedAgentsUserCustomToolResultEvent object
Event sent by the client providing the result of a custom tool execution.
type: "user.custom_tool_result"
id: string
Unique identifier for this event.
custom_tool_use_id: string
The id of the agent.custom_tool_use event this result corresponds to, which can be found in the last session.status_idle event's stop_reason.event_ids field.
content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock
The result content returned by the tool.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
BetaManagedAgentsSearchResultBlock object
A block containing a web search result.
type: "search_result"
citations: BetaManagedAgentsSearchResultCitations
Citation settings for this search result.
enabled: boolean
Whether citations are enabled for this search result.
content: array of BetaManagedAgentsSearchResultContent
Array of text content blocks from the search result.
type: "text"
text: string
The text content.
minLength: 1
source: string
The URL source of the search result.
minLength: 1
title: string
The title of the search result.
minLength: 1
is_error: optional boolean or null
Whether the tool execution resulted in an error.
processed_at: optional string or null
Timestamp when this result was processed.
format: date-time
session_thread_id: optional string or null
Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread.
BetaManagedAgentsAgentCustomToolUseEvent object
Event emitted when the agent calls a custom tool. The session goes idle until the client sends a user.custom_tool_result event with the result.
type: "agent.custom_tool_use"
id: string
Unique identifier for this event.
input: map[unknown]
Input parameters for the tool call.
name: string
Name of the custom tool being called.
processed_at: string
Timestamp when this tool use was processed.
format: date-time
session_thread_id: optional string or null
When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching user.custom_tool_result by custom_tool_use_id, so clients do not send it back.
BetaManagedAgentsAgentMessageEvent object
An agent response event in the session conversation.
type: "agent.message"
id: string
Unique identifier for this event.
content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsRedactedBlock
Array of text blocks comprising the agent response.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsRedactedBlock object
Placeholder for content withheld by Juglow model policy.
processed_at: string
Timestamp when this response was generated.
format: date-time
BetaManagedAgentsAgentThinkingEvent object
Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.
type: "agent.thinking"
id: string
Unique identifier for this event.
processed_at: string
Timestamp when this thinking was produced.
format: date-time
BetaManagedAgentsAgentMCPToolUseEvent object
Event emitted when the agent invokes a tool provided by an MCP server.
type: "agent.mcp_tool_use"
id: string
Unique identifier for this event.
input: map[unknown]
Input parameters for the tool call.
mcp_server_name: string
Name of the MCP server providing the tool.
name: string
Name of the MCP tool being used.
processed_at: string
Timestamp when this event was processed.
format: date-time
evaluated_permission: optional BetaManagedAgentsAgentEvaluatedPermission
The evaluated permission policy for this tool invocation.
"allow"
"ask"
"deny"
evaluation: optional BetaManagedAgentsAgentToolEvaluation
Which resolved permission_policy produced evaluated_permission: always_allow, always_ask, or auto (with the server's per-invocation judgement). Absent only when the server refused the call before any policy applied (for example, the named tool is not enabled in the session); such a refusal has evaluated_permission deny. An event recorded before this field existed reads as the arm its evaluated_permission implies (always_allow for allow, always_ask for ask).
BetaManagedAgentsAgentToolEvaluationAlwaysAllow object
The resolved permission_policy was always_allow; accompanies evaluated_permission "allow".
type: "always_allow"
BetaManagedAgentsAgentToolEvaluationAlwaysAsk object
The resolved permission_policy was always_ask; accompanies evaluated_permission "ask".
type: "always_ask"
BetaManagedAgentsAgentToolEvaluationAuto object
The resolved permission_policy was auto: the server judged this invocation individually.
type: "auto"
evaluated_permission: BetaManagedAgentsAgentAutoEvaluatedPermission
The server's judgement for this invocation.
BetaManagedAgentsAgentAutoEvaluatedPermissionAllow object
The server judged the invocation safe to execute without client approval.
type: "allow"
BetaManagedAgentsAgentAutoEvaluatedPermissionAsk object
The server reached no judgement; the invocation is held for client approval.
type: "ask"
reason_code: string
The judgement's grounds in registry-bound terms, for client branching and audit rather than end-user display. Open registry; currently "indeterminate" (no judgement was reached). Clients must tolerate values outside this set.
maxLength: 64
BetaManagedAgentsAgentAutoEvaluatedPermissionDeny object
The server judged the invocation high-risk; it does not execute and a synthetic error tool result is appended.
type: "deny"
reason_code: string
The judgement's grounds in registry-bound terms. Open registry; currently "high_risk" (judged high-risk; the call does not run). Clients must tolerate values outside this set.
maxLength: 64
session_thread_id: optional string or null
When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching user.tool_confirmation by tool_use_id, so clients do not send it back.
BetaManagedAgentsAgentMCPToolResultEvent object
Event representing the result of an MCP tool execution.
type: "agent.mcp_tool_result"
id: string
Unique identifier for this event.
mcp_tool_use_id: string
The id of the agent.mcp_tool_use event this result corresponds to.
processed_at: string
Timestamp when this event was processed.
format: date-time
content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock
The result content returned by the tool.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
BetaManagedAgentsSearchResultBlock object
A block containing a web search result.
is_error: optional boolean or null
Whether the tool execution resulted in an error.
BetaManagedAgentsAgentToolUseEvent object
Event emitted when the agent invokes a built-in agent tool.
type: "agent.tool_use"
id: string
Unique identifier for this event.
input: map[unknown]
Input parameters for the tool call.
name: string
Name of the agent tool being used.
processed_at: string
Timestamp when this event was processed.
format: date-time
evaluated_permission: optional BetaManagedAgentsAgentEvaluatedPermission
The evaluated permission policy for this tool invocation.
evaluation: optional BetaManagedAgentsAgentToolEvaluation
Which resolved permission_policy produced evaluated_permission: always_allow, always_ask, or auto (with the server's per-invocation judgement). Absent only when the server refused the call before any policy applied (for example, the named tool is not enabled in the session); such a refusal has evaluated_permission deny. An event recorded before this field existed reads as the arm its evaluated_permission implies (always_allow for allow, always_ask for ask).
session_thread_id: optional string or null
When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching user.tool_confirmation or user.tool_result by tool_use_id, so clients do not send it back.
BetaManagedAgentsAgentToolResultEvent object
Event representing the result of an agent tool execution.
type: "agent.tool_result"
id: string
Unique identifier for this event.
processed_at: string
Timestamp when this event was processed.
format: date-time
tool_use_id: string
The id of the agent.tool_use event this result corresponds to.
content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock
The result content returned by the tool.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
BetaManagedAgentsSearchResultBlock object
A block containing a web search result.
is_error: optional boolean or null
Whether the tool execution resulted in an error.
BetaManagedAgentsAgentThreadMessageReceivedEvent object
Delivery event written to the target thread's input stream when an agent-to-agent message arrives.
type: "agent.thread_message_received"
id: string
Unique identifier for this event.
content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock
Message content blocks.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
BetaManagedAgentsRedactedBlock object
Placeholder for content withheld by Juglow model policy.
from_session_thread_id: string
Public sthr_ ID of the thread that sent the message.
processed_at: string
Timestamp when the message was received.
format: date-time
from_agent_name: optional string or null
Name of the callable agent this message came from. Absent when received from the primary agent.
BetaManagedAgentsAgentThreadMessageSentEvent object
Observability event emitted to the sender's output stream when an agent-to-agent message is sent.
type: "agent.thread_message_sent"
id: string
Unique identifier for this event.
content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock
Message content blocks.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
BetaManagedAgentsRedactedBlock object
Placeholder for content withheld by Juglow model policy.
processed_at: string
Timestamp when the message was sent.
format: date-time
to_session_thread_id: string
Public sthr_ ID of the thread the message was sent to.
to_agent_name: optional string or null
Name of the callable agent this message was sent to. Absent when sent to the primary agent.
BetaManagedAgentsAgentThreadContextCompactedEvent object
Indicates that context compaction (summarization) occurred during the session.
type: "agent.thread_context_compacted"
id: string
Unique identifier for this event.
processed_at: string
Timestamp when compaction was processed.
format: date-time
BetaManagedAgentsSessionErrorEvent object
An error event indicating a problem occurred during session execution.
type: "session.error"
id: string
Unique identifier for this event.
error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 5 more
BetaManagedAgentsUnknownError object
An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on retry_status and message alone.
type: "unknown_error"
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
type: "retrying"
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
type: "exhausted"
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
type: "terminal"
BetaManagedAgentsModelOverloadedError object
The model is currently overloaded. Emitted after automatic retries are exhausted.
type: "model_overloaded_error"
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
BetaManagedAgentsModelRateLimitedError object
The model request was rate-limited.
type: "model_rate_limited_error"
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
BetaManagedAgentsModelRequestFailedError object
A model request failed for a reason other than overload or rate-limiting.
type: "model_request_failed_error"
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
BetaManagedAgentsMCPConnectionFailedError object
Failed to connect to an MCP server.
type: "mcp_connection_failed_error"
mcp_server_name: string
Name of the MCP server that failed to connect.
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
BetaManagedAgentsMCPAuthenticationFailedError object
Authentication to an MCP server failed.
type: "mcp_authentication_failed_error"
mcp_server_name: string
Name of the MCP server that failed authentication.
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
BetaManagedAgentsBillingError object
The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state.
type: "billing_error"
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
BetaManagedAgentsCredentialHostUnreachableError object
An environment_variable credential's auth.networking.allowed_hosts includes a host the environment's network policy does not permit.
type: "credential_host_unreachable_error"
credential_id: string
ID of the affected credential.
message: string
Human-readable error description.
retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal
What the client should do next.
BetaManagedAgentsRetryStatusRetrying object
The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
BetaManagedAgentsRetryStatusExhausted object
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
BetaManagedAgentsRetryStatusTerminal object
The session encountered a terminal error and will transition to terminated state.
vault_id: string
ID of the vault containing the affected credential.
processed_at: string
Timestamp when the error occurred.
format: date-time
BetaManagedAgentsSessionStatusRescheduledEvent object
Indicates the session is recovering from an error state and is rescheduled for execution.
type: "session.status_rescheduled"
id: string
Unique identifier for this event.
processed_at: string
Timestamp of status change.
format: date-time
BetaManagedAgentsSessionStatusRunningEvent object
Indicates the session is actively running and the agent is working.
type: "session.status_running"
id: string
Unique identifier for this event.
processed_at: string
Timestamp of status change.
format: date-time
BetaManagedAgentsSessionStatusIdleEvent object
Indicates the agent has paused and is awaiting user input.
type: "session.status_idle"
id: string
Unique identifier for this event.
processed_at: string
Timestamp of status change.
format: date-time
stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached
BetaManagedAgentsSessionEndTurn object
The agent completed its turn naturally and is ready for the next user message.
type: "end_turn"
BetaManagedAgentsSessionRequiresAction object
The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.
type: "requires_action"
event_ids: array of string
The ids of events the agent is blocked on. Resolving fewer than all re-emits session.status_idle with the remainder.
BetaManagedAgentsSessionRetriesExhausted object
The turn ended because repeated errors exhausted the retry budget or an error escalated to retry_status: 'exhausted'.
type: "retries_exhausted"
BetaManagedAgentsSessionBudgetReached object
The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget.
type: "budget_reached"
BetaManagedAgentsSessionStatusTerminatedEvent object
Indicates the session has terminated, either due to an error or completion.
type: "session.status_terminated"
id: string
Unique identifier for this event.
processed_at: string
Timestamp of status change.
format: date-time
BetaManagedAgentsSessionThreadCreatedEvent object
Emitted when a subagent is spawned as a new thread. Written to the parent thread's output stream so clients observing the session see child creation.
type: "session.thread_created"
id: string
Unique identifier for this event.
agent_name: string
Name of the callable agent the thread runs.
processed_at: string
Timestamp when the thread was created.
format: date-time
session_thread_id: string
Public sthr_ ID of the newly created thread.
BetaManagedAgentsSpanOutcomeEvaluationStartEvent object
Emitted when an outcome evaluation cycle begins.
type: "span.outcome_evaluation_start"
id: string
Unique identifier for this event.
iteration: number
0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.
format: int32
outcome_id: string
The outc_ ID of the outcome being evaluated.
processed_at: string
Timestamp when outcome evaluation started.
format: date-time
BetaManagedAgentsSpanOutcomeEvaluationEndEvent object
Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of needs_revision means another evaluation cycle follows; satisfied, max_iterations_reached, failed, or interrupted are terminal — no further evaluation cycles follow.
type: "span.outcome_evaluation_end"
id: string
Unique identifier for this event.
explanation: string
Human-readable explanation of the verdict. For needs_revision, describes which criteria failed and why.
iteration: number
0-indexed revision cycle, matching the corresponding span.outcome_evaluation_start.
format: int32
outcome_evaluation_start_id: string
The id of the corresponding span.outcome_evaluation_start event.
outcome_id: string
The outc_ ID of the outcome being evaluated.
processed_at: string
Timestamp when outcome evaluation ended.
format: date-time
result: string
Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress.
usage: BetaManagedAgentsSpanModelUsage
Aggregate token usage for this evaluation cycle. Sums across all grader model requests within the cycle.
cache_creation_input_tokens: number
Tokens used to create prompt cache in this request.
format: int32
cache_read_input_tokens: number
Tokens read from prompt cache in this request.
format: int32
input_tokens: number
Input tokens consumed by this request.
format: int32
output_tokens: number
Output tokens generated by this request.
format: int32
speed: optional "standard" or "fast" or null
Inference speed tier this request actually ran at. Mirrors usage.speed on /v1/messages. Only present when the fast-mode beta is active.
"standard"
"fast"
BetaManagedAgentsSpanModelRequestStartEvent object
Emitted when a model request is initiated by the agent.
type: "span.model_request_start"
id: string
Unique identifier for this event.
processed_at: string
Timestamp when the model request started.
format: date-time
BetaManagedAgentsSpanModelRequestEndEvent object
Emitted when a model request completes.
type: "span.model_request_end"
id: string
Unique identifier for this event.
is_error: boolean or null
Whether the model request resulted in an error.
model_request_start_id: string
The id of the corresponding span.model_request_start event.
model_usage: BetaManagedAgentsSpanModelUsage
Token usage for this model request.
processed_at: string
Timestamp when the model request completed.
format: date-time
BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object
Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding span.outcome_evaluation_start and span.outcome_evaluation_end events.
type: "span.outcome_evaluation_ongoing"
id: string
Unique identifier for this event.
iteration: number
0-indexed revision cycle, matching the corresponding span.outcome_evaluation_start.
format: int32
outcome_id: string
The outc_ ID of the outcome being evaluated.
processed_at: string
Timestamp when this heartbeat was emitted.
format: date-time
BetaManagedAgentsUserDefineOutcomeEvent object
Echo of a user.define_outcome input event. Carries the server-generated outcome_id that subsequent span.outcome_evaluation_* events reference.
type: "user.define_outcome"
id: string
Unique identifier for this event.
description: string
What the agent should produce. Copied from the input event.
max_iterations: number or null
Evaluate-then-revise cycles before giving up. Default 3, max 20.
format: int32
outcome_id: string
Server-generated outc_ ID for this outcome. Referenced by span.outcome_evaluation_* events and the session's outcome_evaluations list.
processed_at: string
Timestamp when the outcome was accepted.
format: date-time
rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric
How to grade the outcome. File rubrics are currently resolved to their text content; clients should handle both variants.
BetaManagedAgentsFileRubric object
Rubric referenced by a file uploaded via the Files API.
type: "file"
file_id: string
ID of the rubric file.
BetaManagedAgentsTextRubric object
Rubric content provided inline as text.
type: "text"
content: string
Rubric content. Plain text or markdown — the grader treats it as freeform text.
BetaManagedAgentsSessionDeletedEvent object
Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.
type: "session.deleted"
id: string
Unique identifier for this event.
processed_at: string
Timestamp when the session was deleted.
format: date-time
BetaManagedAgentsSessionThreadStatusRunningEvent object
A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
type: "session.thread_status_running"
id: string
Unique identifier for this event.
agent_name: string
Name of the agent the thread runs.
processed_at: string
Timestamp of the status transition.
format: date-time
session_thread_id: string
Public sthr_ ID of the thread that started running.
BetaManagedAgentsSessionThreadStatusIdleEvent object
A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
type: "session.thread_status_idle"
id: string
Unique identifier for this event.
agent_name: string
Name of the agent the thread runs.
processed_at: string
Timestamp of the status transition.
format: date-time
session_thread_id: string
Public sthr_ ID of the thread that went idle.
stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached
BetaManagedAgentsSessionEndTurn object
The agent completed its turn naturally and is ready for the next user message.
BetaManagedAgentsSessionRequiresAction object
The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.
BetaManagedAgentsSessionRetriesExhausted object
The turn ended because repeated errors exhausted the retry budget or an error escalated to retry_status: 'exhausted'.
BetaManagedAgentsSessionBudgetReached object
The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget.
BetaManagedAgentsSessionThreadStatusTerminatedEvent object
A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
type: "session.thread_status_terminated"
id: string
Unique identifier for this event.
agent_name: string
Name of the agent the thread runs.
processed_at: string
Timestamp of the status transition.
format: date-time
session_thread_id: string
Public sthr_ ID of the thread that terminated.
BetaManagedAgentsUserToolResultEvent object
Event sent by the client providing the result of an agent-toolset tool execution. Only valid on self_hosted environments, where sandbox-routed tools are executed by the client rather than the server.
type: "user.tool_result"
id: string
Unique identifier for this event.
tool_use_id: string
The id of the agent.tool_use event this result corresponds to, which can be found in the last session.status_idle event's stop_reason.event_ids field.
content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock
The result content returned by the tool.
BetaManagedAgentsTextBlock object
Regular text content.
BetaManagedAgentsImageBlock object
Image content specified directly as base64 data or as a reference via a URL.
BetaManagedAgentsDocumentBlock object
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
BetaManagedAgentsSearchResultBlock object
A block containing a web search result.
is_error: optional boolean or null
Whether the tool execution resulted in an error.
processed_at: optional string or null
Timestamp when this result was processed.
format: date-time
session_thread_id: optional string or null
Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread.
BetaManagedAgentsSessionThreadStatusRescheduledEvent object
A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
type: "session.thread_status_rescheduled"
id: string
Unique identifier for this event.
agent_name: string
Name of the agent the thread runs.
processed_at: string
Timestamp of the status transition.
format: date-time
session_thread_id: string
Public sthr_ ID of the thread that is retrying.
BetaManagedAgentsSessionUpdatedEvent object
Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn.
type: "session.updated"
id: string
Unique identifier for this event.
processed_at: string
Timestamp when the update was applied.
format: date-time
agent: optional BetaManagedAgentsSessionAgent or null
The session's effective agent configuration after the update. Present only when the update changed agent (tools or mcp_servers); when present it is the full materialised snapshot, not a diff.
type: "agent"
id: string
description: string or null
mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition
type: "url"
name: string
url: string
model: BetaManagedAgentsModelConfig
Model identifier and configuration.
id: BetaManagedAgentsModel
The model that will power your agent.
See models for additional details and options.
string
"haijun-opus-5-5" or "haijun-fable-5-1" or "haijun-sonnet-5" or 12 more
The model that will power your agent.
See models for additional details and options.
"haijun-opus-5-5"
Powerful intelligence for coding, knowledge work, and long-running agents
"haijun-fable-5-1"
Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
"haijun-sonnet-5"
High-performance model for coding and agents
"haijun-fable-5"
Next generation of intelligence for the hardest knowledge work and coding problems
"haijun-opus-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-8"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-7"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-6"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-6"
Best combination of speed and intelligence
"haijun-haiku-4-5"
Fastest model with near-frontier intelligence
"haijun-haiku-4-5-20251001"
Fastest model with near-frontier intelligence
"haijun-opus-4-5"
Powerful intelligence for long-running agents and coding
"haijun-opus-4-5-20251101"
Powerful intelligence for long-running agents and coding
"haijun-sonnet-4-5"
High-performance model for agents and coding
"haijun-sonnet-4-5-20250929"
High-performance model for agents and coding
effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more
How hard Haijun works on each inference call. One of low, medium, high, xhigh, max. Always present; resolved to the per-model default at save time when not supplied.
BetaManagedAgentsEffortLow object
Low effort. Favors latency over reasoning depth.
type: "low"
BetaManagedAgentsEffortMedium object
Medium effort. Balances latency and reasoning depth.
type: "medium"
BetaManagedAgentsEffortHigh object
High effort. Favors reasoning depth.
type: "high"
BetaManagedAgentsEffortXhigh object
Extra-high effort. Not all models accept this level.
type: "xhigh"
BetaManagedAgentsEffortMax object
Maximum effort. Favors reasoning depth over latency.
type: "max"
inference_geo: optional string
Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
speed: optional "standard" or "fast"
Inference speed mode. fast provides significantly faster output token generation at premium pricing. Defaults to standard. Not all models support fast; invalid combinations are rejected at create time.
"standard"
"fast"
multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null
Resolved multiagent orchestration configuration. Null when the agent is single-threaded.
type: "coordinator"
agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor
Full agent definitions the coordinator may spawn as session threads.
BetaManagedAgentsSessionThreadAgent object
Resolved agent definition for a single session_thread. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from Session.agent.
type: "agent"
id: string
description: string or null
mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition
type: "url"
name: string
url: string
model: BetaManagedAgentsModelConfig
Model identifier and configuration.
name: string
tracks: array of BetaManagedAgentsJuglowSkill or BetaManagedAgentsCustomSkill
BetaManagedAgentsJuglowSkill object
A resolved Juglow-managed track.
type: "juglow"
skill_id: string
version: string
BetaManagedAgentsCustomSkill object
A resolved user-created custom track.
type: "custom"
skill_id: string
version: string
system: string or null
tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool
BetaManagedAgentsAgentToolset20260401 object
type: "agent_toolset_20260401"
configs: array of BetaManagedAgentsAgentToolConfig
BetaManagedAgentsBashToolConfig object
Configuration for the bash tool.
type: "bash"
enabled: boolean
name: "bash"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
type: "always_allow"
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
type: "always_ask"
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
type: "auto"
BetaManagedAgentsEditToolConfig object
Configuration for the edit tool.
type: "edit"
enabled: boolean
name: "edit"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsReadToolConfig object
Configuration for the read tool.
type: "read"
enabled: boolean
name: "read"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWriteToolConfig object
Configuration for the write tool.
type: "write"
enabled: boolean
name: "write"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGlobToolConfig object
Configuration for the glob tool.
type: "glob"
enabled: boolean
name: "glob"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGrepToolConfig object
Configuration for the grep tool.
type: "grep"
enabled: boolean
name: "grep"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWebFetchToolConfig object
Configuration for the web_fetch tool.
type: "web_fetch"
enabled: boolean
name: "web_fetch"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
max_content_tokens: optional number or null
format: int32
BetaManagedAgentsWebSearchToolConfig object
Configuration for the web_search tool.
type: "web_search"
enabled: boolean
name: "web_search"
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
allowed_domains: optional array of string
blocked_domains: optional array of string
user_location: optional BetaManagedAgentsUserLocation or null
Approximate user location for search result localization.
type: "approximate"
Location precision. Only "approximate" is supported.
city: optional string or null
City name.
minLength: 1, maxLength: 255
country: optional string or null
Two-letter ISO 3166-1 country code, uppercase.
region: optional string or null
Region or state name.
minLength: 1, maxLength: 255
timezone: optional string or null
IANA timezone identifier, e.g. "America/Los_Angeles".
minLength: 1, maxLength: 255
default_config: BetaManagedAgentsAgentToolsetDefaultConfig
Resolved default configuration for agent tools.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsMCPToolset object
type: "mcp_toolset"
configs: array of BetaManagedAgentsMCPToolConfig
enabled: boolean
name: string
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
default_config: BetaManagedAgentsMCPToolsetDefaultConfig
Resolved default configuration for all tools from an MCP server.
enabled: boolean
permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy
Permission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy object
Tool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy object
Tool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy object
The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
mcp_server_name: string
BetaManagedAgentsCustomTool object
A custom tool as returned in API responses.
type: "custom"
description: string
input_schema: BetaManagedAgentsCustomToolInputSchema
JSON Schema for custom tool input parameters.
type: "object"
properties: optional map[unknown] or null
required: optional array of string or null
name: string
version: number
format: int32
BetaManagedAgentsAdvisor object
Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
type: "advisor"
model: string
The advisor model id.
name: string
tracks: array of BetaManagedAgentsJuglowSkill or BetaManagedAgentsCustomSkill
BetaManagedAgentsJuglowSkill object
A resolved Juglow-managed track.
BetaManagedAgentsCustomSkill object
A resolved user-created custom track.
system: string or null
tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool
BetaManagedAgentsAgentToolset20260401 object
BetaManagedAgentsMCPToolset object
BetaManagedAgentsCustomTool object
A custom tool as returned in API responses.
version: number
format: int32
budget: optional BetaManagedAgentsBudgetLimit or null
The session's budget after the update: the new budget when set or replaced, or null when the update removed it. Present only when the update changed the budget.
type: "limit"
max_list_cost: BetaMonetaryAmount
Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge.
amount: string
Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.
currency: BetaCurrency
Uppercase ISO-4217 currency code. USD is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.
metadata: optional map[string]
The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty.
title: optional string or null
The session's new title. Present only when the update changed it.
BetaManagedAgentsStartEvent object
Opens a preview of a buffered event. Carries the previewed event's type and id only. Followed by zero or more event_delta events with the same event id, normally concluded by the buffered event carrying that id. If the producing model request ends without that event (an error or interrupt mid-stream), its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history.
type: "event_start"
event: BetaManagedAgentsStartEventPreview
The previewed event's type and id. The event type determines which delta types the preview's event_delta events carry: agent.message events stream content_delta fragments; agent.thinking previews are start-only — no deltas follow, and the buffered agent.thinking with the same id concludes them.
BetaManagedAgentsAgentMessagePreview object
type: "agent.message"
id: string
The id the buffered agent.message will carry if it is emitted. Matches the event_id on this preview's event_delta events.
BetaManagedAgentsAgentThinkingPreview object
type: "agent.thinking"
id: string
The id the buffered agent.thinking will carry if it is emitted. Start-only — no event_delta events follow.
BetaManagedAgentsDeltaEvent object
An incremental update to an event that is still being streamed. Deltas are best-effort and may stop early; when the buffered event with id == event_id is produced it carries the complete content. A model request that ends early (an error or interrupt) produces no buffered event — its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history.
type: "event_delta"
delta: BetaManagedAgentsDeltaContent
One fragment of the previewed event. The delta type is named for the previewed event's field it streams into: agent.message events stream content_delta fragments, each a partial element of the content array.
type: "content_delta"
content: BetaManagedAgentsTextBlock
A partial element of the content array at index, typed like the element itself — the same shape the buffered agent.message carries in content.
index: optional number
Which entry in the previewed event's content array this fragment lands in. Insert content as that entry when the index is new; append to the existing entry otherwise.
event_id: string
The id of the event being previewed. Matches event.id on the corresponding event_start and the buffered event that reconciles the preview.
BetaManagedAgentsSystemMessageEvent object
A mid-conversation system message event. Carries system-role content that is appended to the session as a role: "system" turn.
type: "system.message"
id: string
Unique identifier for this event.
content: array of BetaManagedAgentsSystemContentBlock
System content blocks. Text-only.
type: "text"
text: string
The text content.
minLength: 1
processed_at: optional string or null
Timestamp when this system message was processed.
format: date-time
BetaManagedAgentsSessionUsageEvent object
Periodic snapshot of the session's cumulative usage and tracked list cost.
type: "session.usage"
id: string
Unique identifier for this event.
processed_at: string
Timestamp when the snapshot was taken.
format: date-time
usage: BetaManagedAgentsSessionUsageSnapshot
The session's cumulative usage at the snapshot time.
active_seconds: optional number
Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once. This is the duration the session's runtime cost is priced on.
format: double
cache_creation: optional BetaManagedAgentsCacheCreationUsage
Tokens used to create prompt cache entries, broken down by cache TTL.
ephemeral_1h_input_tokens: optional number
Tokens used to create 1-hour ephemeral cache entries.
format: int32
ephemeral_5m_input_tokens: optional number
Tokens used to create 5-minute ephemeral cache entries.
format: int32
cache_read_input_tokens: optional number
Total tokens read from prompt cache.
format: int32
input_tokens: optional number
Total input tokens consumed across all turns.
format: int32
list_cost: optional BetaMonetaryAmount
Cumulative list cost of the session across all turns, priced at public list rates.
output_tokens: optional number
Total output tokens generated across all turns.
format: int32
server_tool_use: optional BetaManagedAgentsServerToolUsage
Cumulative server-executed tool usage across all turns.
web_fetch_requests: optional number
Number of server-executed web fetch requests.
format: int32
web_search_requests: optional number
Number of server-executed web search requests.
format: int32
budget: optional BetaManagedAgentsBudgetLimit or null
The session's configured budget at the snapshot time, or null when the session has no budget.
Example
curl https://haijun.my.id/v1/sessions/$SESSION_ID/threads/$THREAD_ID/stream \
-H 'juglow-version: 2023-06-01' \
-H 'juglow-beta: managed-agents-2026-04-01' \
-H "X-Api-Key: $JUGLOW_API_KEY"Response (200)
{
"id": "sevt_011CZkZGOp0iBcp4kaQSihUmy",
"content": [
{
"text": "Where is my order #1234?",
"type": "text"
}
],
"type": "user.message",
"processed_at": "2026-03-15T10:00:00Z"
}