@labelbox/recursion-sdk 0.0.165 → 0.0.167

package/dist/generated/sdk.gen.d.ts

@@ -37,7 +37,7 @@ export declare class ManagedAgents extends HeyApiClient {
     /**
      * Create an agent and immutable version
      *
-     * Creates an agent and its first immutable version, and returns the agent resolved to that version. Exactly one of model or model_ref_id is required alongside name and system. The body is also accepted as application/x-yaml with the same schema. Any vault named in default_vault_ids must already exist.
+     * Creates an agent and its first immutable version, and returns the agent resolved to that version. Exactly one of model or model_ref_id is required alongside name and system. The body is also accepted as application/x-yaml with the same schema. Any vault named in default_vault_ids must already exist. Invalid model_config and unsupported reasoning_effort values return 400, including when a reachable gateway model publishes no exact options; an unconfigured or unreachable gateway that prevents verification returns 503.
      */
     createAgent<ThrowOnError extends boolean = false>(parameters?: {
         body?: ManagedAgentsCreateAgentRequest;
@@ -61,7 +61,7 @@ export declare class ManagedAgents extends HeyApiClient {
     /**
      * Update agent and create a new immutable version
      *
-     * Applies a partial update and returns the agent resolved to the new version. Agent versions are immutable, so every accepted update mints a new one rather than editing history; omitted fields keep their current values. Running sessions keep the version they started with.
+     * Applies a partial update and returns the agent resolved to the new version. Agent versions are immutable, so every accepted update mints a new one rather than editing history; omitted fields keep their current values. Running sessions keep the version they started with. Invalid model_config and unsupported new or changed reasoning_effort values return 400, including when a reachable gateway model publishes no exact options; an unconfigured or unreachable gateway that prevents verification returns 503.
      */
     updateAgent<ThrowOnError extends boolean = false>(parameters: {
         agent_id: string;
@@ -488,7 +488,7 @@ export declare class ManagedAgents extends HeyApiClient {
     /**
      * Start a managed session
      *
-     * Starts a managed agent session and returns 202 with its session_id and status_path; the agent runs asynchronously, so poll getSession or subscribe with streamSessionEvents to follow it. Sandbox compute is provisioned here, which is where a session begins costing money. Send an Idempotency-Key header to make retries safe: the same key with the same body returns the original session, and with a different body is rejected.
+     * Starts a managed agent session and returns 202 with its session_id and status_path; the agent runs asynchronously, so poll getSession or subscribe with streamSessionEvents to follow it. Sandbox compute is provisioned here, which is where a session begins costing money. Send an Idempotency-Key header to make retries safe: the same key with the same body returns the original session, and with a different body is rejected. A reasoning_effort incompatible with the selected model or its frozen output capacity returns 400 before provisioning; a temporarily unavailable model reference or catalog dependency returns 503.
      */
     startSession<ThrowOnError extends boolean = false>(parameters?: {
         'Idempotency-Key'?: string;

package/dist/generated/sdk.gen.js

@@ -40,7 +40,7 @@ export class ManagedAgents extends HeyApiClient {
     /**
      * Create an agent and immutable version
      *
-     * Creates an agent and its first immutable version, and returns the agent resolved to that version. Exactly one of model or model_ref_id is required alongside name and system. The body is also accepted as application/x-yaml with the same schema. Any vault named in default_vault_ids must already exist.
+     * Creates an agent and its first immutable version, and returns the agent resolved to that version. Exactly one of model or model_ref_id is required alongside name and system. The body is also accepted as application/x-yaml with the same schema. Any vault named in default_vault_ids must already exist. Invalid model_config and unsupported reasoning_effort values return 400, including when a reachable gateway model publishes no exact options; an unconfigured or unreachable gateway that prevents verification returns 503.
      */
     createAgent(parameters, options) {
         const params = buildClientParams([parameters], [{ args: [{ key: 'body', map: 'body' }] }]);
@@ -90,7 +90,7 @@ export class ManagedAgents extends HeyApiClient {
     /**
      * Update agent and create a new immutable version
      *
-     * Applies a partial update and returns the agent resolved to the new version. Agent versions are immutable, so every accepted update mints a new one rather than editing history; omitted fields keep their current values. Running sessions keep the version they started with.
+     * Applies a partial update and returns the agent resolved to the new version. Agent versions are immutable, so every accepted update mints a new one rather than editing history; omitted fields keep their current values. Running sessions keep the version they started with. Invalid model_config and unsupported new or changed reasoning_effort values return 400, including when a reachable gateway model publishes no exact options; an unconfigured or unreachable gateway that prevents verification returns 503.
      */
     updateAgent(parameters, options) {
         const params = buildClientParams([parameters], [{ args: [{ in: 'path', key: 'agent_id' }, { key: 'body', map: 'body' }] }]);
@@ -929,7 +929,7 @@ export class ManagedAgents extends HeyApiClient {
     /**
      * Start a managed session
      *
-     * Starts a managed agent session and returns 202 with its session_id and status_path; the agent runs asynchronously, so poll getSession or subscribe with streamSessionEvents to follow it. Sandbox compute is provisioned here, which is where a session begins costing money. Send an Idempotency-Key header to make retries safe: the same key with the same body returns the original session, and with a different body is rejected.
+     * Starts a managed agent session and returns 202 with its session_id and status_path; the agent runs asynchronously, so poll getSession or subscribe with streamSessionEvents to follow it. Sandbox compute is provisioned here, which is where a session begins costing money. Send an Idempotency-Key header to make retries safe: the same key with the same body returns the original session, and with a different body is rejected. A reasoning_effort incompatible with the selected model or its frozen output capacity returns 400 before provisioning; a temporarily unavailable model reference or catalog dependency returns 503.
      */
     startSession(parameters, options) {
         const params = buildClientParams([parameters], [{ args: [{ in: 'headers', key: 'Idempotency-Key' }, { key: 'body', map: 'body' }] }]);

package/dist/generated/types.gen.d.ts

@@ -8982,6 +8982,10 @@ export type ManagedAgentsGatewayModel = {
      * Whether the gateway can stream responses for this model. False means turns are only available as a single complete response.
      */
     streaming?: boolean;
+    /**
+     * Exact reasoning_effort strings LiteLLM reports for this model group. Omitted means unknown; [] means no explicit effort is supported; a non-empty list is exhaustive. Omit reasoning_effort to use the provider's current default.
+     */
+    supported_reasoning_efforts?: unknown;
     /**
      * Whether the gateway reports that this exact model accepts user image content on its configured wire.
      */
@@ -9015,7 +9019,7 @@ export type ManagedAgentsInferenceConfig = {
         [key: string]: unknown;
     };
     /**
-     * Thinking-budget hint for reasoning-capable models, e.g. low, medium, or high. Ignored by models that do not support reasoning.
+     * Provider-native reasoning depth value. For gateway models, use one of supported_reasoning_efforts from the models catalog; omit it to follow the provider's current default.
      */
     reasoning_effort?: string;
     /**

package/dist/reference/domains.d.ts

@@ -58,8 +58,12 @@ export declare const DOMAINS: readonly [{
     readonly id: "integrations";
     readonly title: "Integrations";
     readonly order: 13;
+}, {
+    readonly id: "managed-agents";
+    readonly title: "Managed Agents";
+    readonly order: 14;
 }];
-/** Union of the thirteen canonical domain ids. */
+/** Union of the fourteen canonical domain ids. */
 export type DomainId = (typeof DOMAINS)[number]['id'];
 /** Runtime guard: is `value` one of the canonical domain ids? */
 export declare function isDomainId(value: unknown): value is DomainId;

package/dist/reference/domains.js

@@ -1,6 +1,6 @@
 // Canonical **product-domain taxonomy** — the single source of truth for the
 // docs information architecture. The How-to (recipes) and Explanation (concepts)
-// quadrants group their entries under these thirteen flat domains; Reference keeps
+// quadrants group their entries under these fourteen flat domains; Reference keeps
 // its own deep, spec-derived tree (it is not domain-grouped).
 //
 // Consumed by the frontend docs nav, the `rl` CLI, and the dx generators. The
@@ -24,6 +24,7 @@ export const DOMAINS = [
     { id: 'cost', title: 'Cost', order: 11 },
     { id: 'administration', title: 'Administration', order: 12 },
     { id: 'integrations', title: 'Integrations', order: 13 },
+    { id: 'managed-agents', title: 'Managed Agents', order: 14 },
 ];
 const DOMAIN_IDS = new Set(DOMAINS.map((d) => d.id));
 /** Runtime guard: is `value` one of the canonical domain ids? */

package/dist/reference/recipes-reference.generated.js

@@ -4661,6 +4661,140 @@ export const RECIPE_REFERENCE = {
             ],
         },
     },
+    'define-a-session-outcome': {
+        id: 'define-a-session-outcome',
+        title: 'Define a session outcome',
+        goal: 'Give a session a rubric so the agent is graded against a checkable bar, then read the verdict it earned.',
+        category: 'managed-agents',
+        video: 'define-a-session-outcome.mp4',
+        walkthrough: [
+            {
+                caption: 'Start a session with an outcome',
+                image: '01-start-a-session-with-an-outcome.png',
+                description: 'The rubric travels with the start request: the session is graded against it from the first turn.',
+            },
+            {
+                caption: 'Wait for the graded session, then read the verdict',
+                image: '02-wait-for-the-graded-session-then-read-the-verdict.png',
+                description: 'A graded session ends once the grader has run its revision passes, and the outcome then carries its evaluations: a per-criterion verdict with rationale.',
+            },
+        ],
+        steps: [
+            {
+                kind: 'sdk',
+                operationId: 'managedAgentsCreateEnvironment',
+                caption: 'Create the environment the agent works in',
+                phase: 'setup',
+                inputs: {
+                    name: {
+                        value: 'Graded sandbox',
+                    },
+                    provider: {
+                        value: 'runs',
+                    },
+                },
+                captures: {
+                    environmentId: 'environment_id',
+                },
+            },
+            {
+                kind: 'sdk',
+                operationId: 'managedAgentsCreateAgent',
+                caption: 'Create the agent',
+                phase: 'setup',
+                inputs: {
+                    name: {
+                        value: 'Report writer',
+                    },
+                    system: {
+                        value: 'Write the requested report. Follow every instruction exactly.',
+                    },
+                    model: {
+                        value: '<gatewayModel>',
+                    },
+                },
+                captures: {
+                    agentId: 'agent_id',
+                },
+            },
+            {
+                kind: 'sdk',
+                operationId: 'managedAgentsStartSession',
+                caption: 'Start a session with an outcome',
+                phase: 'main',
+                inputs: {
+                    agent_id: {
+                        $ref: 'agentId',
+                    },
+                    environment_id: {
+                        $ref: 'environmentId',
+                    },
+                    message: {
+                        value: 'Write a two-sentence summary of what a managed agent session is.',
+                    },
+                    outcome: {
+                        value: {
+                            description: 'A two-sentence summary of what a managed agent session is.',
+                            rubric: '- The summary is exactly two sentences.\n- The summary names the sandbox the session runs in.',
+                            max_iterations: 3,
+                        },
+                    },
+                },
+                captures: {
+                    sessionId: 'session_id',
+                },
+            },
+            {
+                kind: 'sdk',
+                operationId: 'managedAgentsGetSession',
+                caption: 'Wait for the graded session to finish',
+                phase: 'main',
+                inputs: {
+                    session_id: {
+                        $ref: 'sessionId',
+                    },
+                },
+                captures: {
+                    sessionStatus: 'status',
+                },
+            },
+            {
+                kind: 'sdk',
+                operationId: 'managedAgentsListSessionOutcomes',
+                caption: 'Read the verdict',
+                phase: 'main',
+                inputs: {
+                    session_id: {
+                        $ref: 'sessionId',
+                    },
+                },
+                captures: {
+                    outcomes: 'outcomes',
+                },
+            },
+        ],
+        sdk: {
+            setup: "// Create the environment the agent works in\nconst managedAgent = await rl.managedAgents.createEnvironment({\n  body: {\n    name: 'Graded sandbox',\n    provider: 'runs',\n  },\n});\nconst environmentId = managedAgent.environment_id;\n\n// Create the agent\nconst managedAgent2 = await rl.managedAgents.createAgent({\n  body: {\n    model: '<gatewayModel>',\n    name: 'Report writer',\n    system: 'Write the requested report. Follow every instruction exactly.',\n  },\n});\nconst agentId = managedAgent2.agent_id;",
+            main: "// Start a session with an outcome\nconst managedAgent3 = await rl.managedAgents.startSession({\n  body: {\n    agent_id: agentId,\n    environment_id: environmentId,\n    message: 'Write a two-sentence summary of what a managed agent session is.',\n    outcome: { description: 'A two-sentence summary of what a managed agent session is.', rubric: '- The summary is exactly two sentences.\\n- The summary names the sandbox the session runs in.', max_iterations: 3 },\n  },\n});\nconst sessionId = managedAgent3.session_id;\n\n// Wait for the graded session to finish\nlet managedAgent4;\nconst managedAgent4Deadline = Date.now() + 900000;\nfor (;;) {\n  managedAgent4 = await rl.managedAgents.getSession({\n    session_id: sessionId,\n  });\n  if (['failed', 'cancelled'].includes(managedAgent4.status)) throw new Error('reached a terminal failure state: ' + managedAgent4.status);\n  if (['completed'].includes(managedAgent4.status)) break;\n  if (Date.now() > managedAgent4Deadline) throw new Error('timed out after 900000ms waiting for a terminal state');\n  await new Promise((resolve) => setTimeout(resolve, 10000));\n}\nconst sessionStatus = managedAgent4.status;\n\n// Read the verdict\nconst managedAgent5 = await rl.managedAgents.listSessionOutcomes({\n  session_id: sessionId,\n});\nconst outcomes = managedAgent5.outcomes;",
+        },
+        cli: {
+            setup: '# Create the environment the agent works in\nENVIRONMENT_ID=$(rl managed-agents create-environment \\\n  --data "{ \\"name\\": \\"Graded sandbox\\", \\"provider\\": \\"runs\\" }" \\\n  | jq -r \'.environment_id\')\n\n# Create the agent\nAGENT_ID=$(rl managed-agents create-agent \\\n  --data "{ \\"model\\": \\"<gatewayModel>\\", \\"name\\": \\"Report writer\\", \\"system\\": \\"Write the requested report. Follow every instruction exactly.\\" }" \\\n  | jq -r \'.agent_id\')',
+            main: '# Start a session with an outcome\nSESSION_ID=$(rl managed-agents start-session \\\n  --data "{ \\"agent_id\\": \\"$AGENT_ID\\", \\"environment_id\\": \\"$ENVIRONMENT_ID\\", \\"message\\": \\"Write a two-sentence summary of what a managed agent session is.\\", \\"outcome\\": { \\"description\\": \\"A two-sentence summary of what a managed agent session is.\\", \\"rubric\\": \\"- The summary is exactly two sentences.\\\\n- The summary names the sandbox the session runs in.\\", \\"max_iterations\\": 3 } }" \\\n  | jq -r \'.session_id\')\n\n# Wait for the graded session to finish\ndeadline=$(( $(date +%s) + 900 ))\nwhile :; do\n  response=$(rl managed-agents get-session \\\n  --session_id "$SESSION_ID")\n  case "$(printf \'%s\' "$response" | jq -r \'.status\')" in failed|cancelled) echo "reached a terminal failure state: $response" >&2; exit 1 ;; esac\n  case "$(printf \'%s\' "$response" | jq -r \'.status\')" in completed) break ;; esac\n  [ "$(date +%s)" -ge "$deadline" ] && { echo "timed out waiting for a terminal state" >&2; exit 1; }\n  sleep 10\ndone\nSESSION_STATUS=$(printf \'%s\' "$response" | jq -r \'.status\')\n\n# Read the verdict\nOUTCOMES=$(rl managed-agents list-session-outcomes \\\n  --session_id "$SESSION_ID" \\\n  | jq -r \'.outcomes\')',
+        },
+        curl: {
+            setup: '# Create the environment the agent works in\nENVIRONMENT_ID=$(curl -s -X POST "https://api.recursion.labelbox.com/managed-agents/v1/environments" \\\n  -H "Authorization: Bearer $LABELBOX_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d "{ \\"name\\": \\"Graded sandbox\\", \\"provider\\": \\"runs\\" }" \\\n  | jq -r \'.environment_id\')\n\n# Create the agent\nAGENT_ID=$(curl -s -X POST "https://api.recursion.labelbox.com/managed-agents/v1/agents" \\\n  -H "Authorization: Bearer $LABELBOX_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d "{ \\"model\\": \\"<gatewayModel>\\", \\"name\\": \\"Report writer\\", \\"system\\": \\"Write the requested report. Follow every instruction exactly.\\" }" \\\n  | jq -r \'.agent_id\')',
+            main: '# Start a session with an outcome\nSESSION_ID=$(curl -s -X POST "https://api.recursion.labelbox.com/managed-agents/v1/sessions" \\\n  -H "Authorization: Bearer $LABELBOX_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d "{ \\"agent_id\\": \\"$AGENT_ID\\", \\"environment_id\\": \\"$ENVIRONMENT_ID\\", \\"message\\": \\"Write a two-sentence summary of what a managed agent session is.\\", \\"outcome\\": { \\"description\\": \\"A two-sentence summary of what a managed agent session is.\\", \\"rubric\\": \\"- The summary is exactly two sentences.\\\\n- The summary names the sandbox the session runs in.\\", \\"max_iterations\\": 3 } }" \\\n  | jq -r \'.session_id\')\n\n# Wait for the graded session to finish\ndeadline=$(( $(date +%s) + 900 ))\nwhile :; do\n  response=$(curl -s -X GET "https://api.recursion.labelbox.com/managed-agents/v1/sessions/$SESSION_ID" \\\n  -H "Authorization: Bearer $LABELBOX_API_KEY")\n  case "$(printf \'%s\' "$response" | jq -r \'.status\')" in failed|cancelled) echo "reached a terminal failure state: $response" >&2; exit 1 ;; esac\n  case "$(printf \'%s\' "$response" | jq -r \'.status\')" in completed) break ;; esac\n  [ "$(date +%s)" -ge "$deadline" ] && { echo "timed out waiting for a terminal state" >&2; exit 1; }\n  sleep 10\ndone\nSESSION_STATUS=$(printf \'%s\' "$response" | jq -r \'.status\')\n\n# Read the verdict\nOUTCOMES=$(curl -s -X GET "https://api.recursion.labelbox.com/managed-agents/v1/sessions/$SESSION_ID/outcomes" \\\n  -H "Authorization: Bearer $LABELBOX_API_KEY" \\\n  | jq -r \'.outcomes\')',
+        },
+        related: {
+            variationOf: 'run-an-agent-session',
+            learnMore: [
+                {
+                    type: 'concept',
+                    id: 'how-grading-works',
+                },
+            ],
+        },
+    },
     'delete-a-draft-version': {
         id: 'delete-a-draft-version',
         title: 'Delete a draft version',
@@ -6288,6 +6422,136 @@ export const RECIPE_REFERENCE = {
             ],
         },
     },
+    'give-an-agent-a-skill': {
+        id: 'give-an-agent-a-skill',
+        title: 'Give an agent a skill',
+        goal: 'Write a procedure as an Agent Skill and attach it to an agent, so every session it starts loads that procedure.',
+        category: 'managed-agents',
+        video: 'give-an-agent-a-skill.mp4',
+        walkthrough: [
+            {
+                caption: 'Write the skill document',
+                image: '01-write-the-skill-document.png',
+                description: 'A skill is a SKILL.md: YAML frontmatter naming and describing it, then the procedure itself.',
+            },
+            {
+                caption: 'Attach the skill to the agent',
+                image: '02-attach-the-skill-to-the-agent.png',
+                description: 'Attaching by skill id follows the skill: the agent picks up each new version as it is published.',
+            },
+            {
+                caption: 'Confirm the agent carries the skill',
+                image: '03-confirm-the-agent-carries-the-skill.png',
+                description: 'Reading the agent back shows the attachment as the service stored it, on a new agent version.',
+            },
+        ],
+        steps: [
+            {
+                kind: 'sdk',
+                operationId: 'managedAgentsCreateAgent',
+                caption: 'Create the agent the skill is for',
+                phase: 'setup',
+                inputs: {
+                    name: {
+                        value: 'Release notes writer',
+                    },
+                    system: {
+                        value: 'Follow the attached procedures exactly.',
+                    },
+                    model: {
+                        value: '<gatewayModel>',
+                    },
+                },
+                captures: {
+                    agentId: 'agent_id',
+                },
+            },
+            {
+                kind: 'sdk',
+                operationId: 'managedAgentsCreateSkill',
+                caption: 'Write the skill document',
+                phase: 'main',
+                inputs: {
+                    document: {
+                        value: '---\nname: write-release-notes\ndescription: Turn a list of merged changes into release notes grouped by audience impact.\n---\n\n# Write release notes\n\n1. Group the merged changes by who notices them: users, operators, nobody.\n2. Drop the "nobody" group.\n3. Write one line per change, in the reader\'s language, not the commit\'s.',
+                    },
+                    display_title: {
+                        value: 'Write release notes',
+                    },
+                },
+                captures: {
+                    skillId: 'skill_id',
+                },
+            },
+            {
+                kind: 'sdk',
+                operationId: 'managedAgentsUpdateAgent',
+                caption: 'Attach the skill to the agent',
+                phase: 'main',
+                inputs: {
+                    agent_id: {
+                        $ref: 'agentId',
+                    },
+                    skills: {
+                        value: [
+                            {
+                                skill_id: {
+                                    $ref: 'skillId',
+                                },
+                            },
+                        ],
+                    },
+                },
+                captures: {
+                    agentVersionId: 'latest_agent_version_id',
+                },
+            },
+            {
+                kind: 'sdk',
+                operationId: 'managedAgentsGetAgent',
+                caption: 'Confirm the agent carries the skill',
+                phase: 'main',
+                inputs: {
+                    agent_id: {
+                        $ref: 'agentId',
+                    },
+                },
+                captures: {
+                    attachedSkills: 'skills',
+                },
+            },
+        ],
+        sdk: {
+            setup: "// Create the agent the skill is for\nconst managedAgent = await rl.managedAgents.createAgent({\n  body: {\n    model: '<gatewayModel>',\n    name: 'Release notes writer',\n    system: 'Follow the attached procedures exactly.',\n  },\n});\nconst agentId = managedAgent.agent_id;",
+            main: "// Write the skill document\nconst managedAgent2 = await rl.managedAgents.createSkill({\n  body: {\n    display_title: 'Write release notes',\n    document: '---\\nname: write-release-notes\\ndescription: Turn a list of merged changes into release notes grouped by audience impact.\\n---\\n\\n# Write release notes\\n\\n1. Group the merged changes by who notices them: users, operators, nobody.\\n2. Drop the \"nobody\" group.\\n3. Write one line per change, in the reader\\'s language, not the commit\\'s.',\n  },\n});\nconst skillId = managedAgent2.skill_id;\n\n// Attach the skill to the agent\nconst managedAgent3 = await rl.managedAgents.updateAgent({\n  agent_id: agentId,\n  body: {\n    agent_id: agentId,\n    skills: [{ skill_id: skillId }],\n  },\n});\nconst agentVersionId = managedAgent3.latest_agent_version_id;\n\n// Confirm the agent carries the skill\nconst managedAgent4 = await rl.managedAgents.getAgent({\n  agent_id: agentId,\n});\nconst attachedSkills = managedAgent4.skills;",
+        },
+        cli: {
+            setup: '# Create the agent the skill is for\nAGENT_ID=$(rl managed-agents create-agent \\\n  --data "{ \\"model\\": \\"<gatewayModel>\\", \\"name\\": \\"Release notes writer\\", \\"system\\": \\"Follow the attached procedures exactly.\\" }" \\\n  | jq -r \'.agent_id\')',
+            main: '# Write the skill document\nSKILL_ID=$(rl managed-agents create-skill \\\n  --data "{ \\"display_title\\": \\"Write release notes\\", \\"document\\": \\"---\\\\nname: write-release-notes\\\\ndescription: Turn a list of merged changes into release notes grouped by audience impact.\\\\n---\\\\n\\\\n# Write release notes\\\\n\\\\n1. Group the merged changes by who notices them: users, operators, nobody.\\\\n2. Drop the \\\\\\"nobody\\\\\\" group.\\\\n3. Write one line per change, in the reader\'s language, not the commit\'s.\\" }" \\\n  | jq -r \'.skill_id\')\n\n# Attach the skill to the agent\nAGENT_VERSION_ID=$(rl managed-agents update-agent \\\n  --agent_id "$AGENT_ID" \\\n  --data "{ \\"agent_id\\": \\"$AGENT_ID\\", \\"skills\\": [{ \\"skill_id\\": \\"$SKILL_ID\\" }] }" \\\n  | jq -r \'.latest_agent_version_id\')\n\n# Confirm the agent carries the skill\nATTACHED_SKILLS=$(rl managed-agents get-agent \\\n  --agent_id "$AGENT_ID" \\\n  | jq -r \'.skills\')',
+        },
+        curl: {
+            setup: '# Create the agent the skill is for\nAGENT_ID=$(curl -s -X POST "https://api.recursion.labelbox.com/managed-agents/v1/agents" \\\n  -H "Authorization: Bearer $LABELBOX_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d "{ \\"model\\": \\"<gatewayModel>\\", \\"name\\": \\"Release notes writer\\", \\"system\\": \\"Follow the attached procedures exactly.\\" }" \\\n  | jq -r \'.agent_id\')',
+            main: '# Write the skill document\nSKILL_ID=$(curl -s -X POST "https://api.recursion.labelbox.com/managed-agents/v1/skills" \\\n  -H "Authorization: Bearer $LABELBOX_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d "{ \\"display_title\\": \\"Write release notes\\", \\"document\\": \\"---\\\\nname: write-release-notes\\\\ndescription: Turn a list of merged changes into release notes grouped by audience impact.\\\\n---\\\\n\\\\n# Write release notes\\\\n\\\\n1. Group the merged changes by who notices them: users, operators, nobody.\\\\n2. Drop the \\\\\\"nobody\\\\\\" group.\\\\n3. Write one line per change, in the reader\'s language, not the commit\'s.\\" }" \\\n  | jq -r \'.skill_id\')\n\n# Attach the skill to the agent\nAGENT_VERSION_ID=$(curl -s -X PATCH "https://api.recursion.labelbox.com/managed-agents/v1/agents/$AGENT_ID" \\\n  -H "Authorization: Bearer $LABELBOX_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d "{ \\"agent_id\\": \\"$AGENT_ID\\", \\"skills\\": [{ \\"skill_id\\": \\"$SKILL_ID\\" }] }" \\\n  | jq -r \'.latest_agent_version_id\')\n\n# Confirm the agent carries the skill\nATTACHED_SKILLS=$(curl -s -X GET "https://api.recursion.labelbox.com/managed-agents/v1/agents/$AGENT_ID" \\\n  -H "Authorization: Bearer $LABELBOX_API_KEY" \\\n  | jq -r \'.skills\')',
+        },
+        related: {
+            requires: [
+                {
+                    type: 'state',
+                    explanation: 'an agent exists to attach the skill to',
+                    via: {
+                        type: 'recipe',
+                        id: 'run-an-agent-session',
+                    },
+                },
+            ],
+            learnMore: [
+                {
+                    type: 'resource',
+                    id: 'managed-agents',
+                },
+            ],
+        },
+    },
     'grade-with-a-composite-grader': {
         id: 'grade-with-a-composite-grader',
         title: 'Grade with a composite grader',
@@ -9823,6 +10087,150 @@ export const RECIPE_REFERENCE = {
             ],
         },
     },
+    'run-an-agent-session': {
+        id: 'run-an-agent-session',
+        title: 'Run an agent session',
+        goal: 'Give a managed agent a sandboxed environment and a task, then watch the session run to completion and read what it did.',
+        category: 'managed-agents',
+        video: 'run-an-agent-session.mp4',
+        walkthrough: [
+            {
+                caption: 'Create the environment the agent works in',
+                image: '01-create-the-environment-the-agent-works-in.png',
+                description: 'The environment is the sandbox: its runtime, image, and setup commands are what the agent gets a shell in.',
+            },
+            {
+                caption: 'Create the agent',
+                image: '02-create-the-agent.png',
+                description: 'An agent is a name, a system prompt, and a model — the definition a session snapshots.',
+            },
+            {
+                caption: 'Start a session',
+                image: '03-start-a-session.png',
+                description: 'Starting is accepted, not finished: the response carries the session id to observe.',
+            },
+            {
+                caption: 'Wait for the session to finish',
+                image: '04-wait-for-the-session-to-finish.png',
+                description: 'The session provisions its sandbox, runs the agent loop, and lands on a terminal status.',
+            },
+            {
+                caption: 'Read what the agent did',
+                image: '05-read-what-the-agent-did.png',
+                description: 'The event timeline is the durable record of the run — messages, tool calls, and results.',
+            },
+        ],
+        steps: [
+            {
+                kind: 'sdk',
+                operationId: 'managedAgentsCreateEnvironment',
+                caption: 'Create the environment the agent works in',
+                phase: 'setup',
+                inputs: {
+                    name: {
+                        value: 'Research sandbox',
+                    },
+                    provider: {
+                        value: 'runs',
+                    },
+                    description: {
+                        value: 'Sandbox for the quickstart research session.',
+                    },
+                },
+                captures: {
+                    environmentId: 'environment_id',
+                },
+            },
+            {
+                kind: 'sdk',
+                operationId: 'managedAgentsCreateAgent',
+                caption: 'Create the agent',
+                phase: 'setup',
+                inputs: {
+                    name: {
+                        value: 'Research assistant',
+                    },
+                    system: {
+                        value: 'Research the task, then write a concise report of what you found.',
+                    },
+                    model: {
+                        value: '<gatewayModel>',
+                    },
+                },
+                captures: {
+                    agentId: 'agent_id',
+                },
+            },
+            {
+                kind: 'sdk',
+                operationId: 'managedAgentsStartSession',
+                caption: 'Start a session',
+                phase: 'main',
+                inputs: {
+                    agent_id: {
+                        $ref: 'agentId',
+                    },
+                    environment_id: {
+                        $ref: 'environmentId',
+                    },
+                    message: {
+                        value: 'Write a one-paragraph summary of what a managed agent session is.',
+                    },
+                },
+                captures: {
+                    sessionId: 'session_id',
+                },
+            },
+            {
+                kind: 'sdk',
+                operationId: 'managedAgentsGetSession',
+                caption: 'Wait for the session to finish',
+                phase: 'main',
+                inputs: {
+                    session_id: {
+                        $ref: 'sessionId',
+                    },
+                },
+                captures: {
+                    sessionStatus: 'status',
+                },
+            },
+            {
+                kind: 'sdk',
+                operationId: 'managedAgentsListSessionEvents',
+                caption: 'Read what the agent did',
+                phase: 'main',
+                inputs: {
+                    session_id: {
+                        $ref: 'sessionId',
+                    },
+                },
+                captures: {
+                    events: 'events',
+                },
+            },
+        ],
+        sdk: {
+            setup: "// Create the environment the agent works in\nconst managedAgent = await rl.managedAgents.createEnvironment({\n  body: {\n    description: 'Sandbox for the quickstart research session.',\n    name: 'Research sandbox',\n    provider: 'runs',\n  },\n});\nconst environmentId = managedAgent.environment_id;\n\n// Create the agent\nconst managedAgent2 = await rl.managedAgents.createAgent({\n  body: {\n    model: '<gatewayModel>',\n    name: 'Research assistant',\n    system: 'Research the task, then write a concise report of what you found.',\n  },\n});\nconst agentId = managedAgent2.agent_id;",
+            main: "// Start a session\nconst managedAgent3 = await rl.managedAgents.startSession({\n  body: {\n    agent_id: agentId,\n    environment_id: environmentId,\n    message: 'Write a one-paragraph summary of what a managed agent session is.',\n  },\n});\nconst sessionId = managedAgent3.session_id;\n\n// Wait for the session to finish\nlet managedAgent4;\nconst managedAgent4Deadline = Date.now() + 900000;\nfor (;;) {\n  managedAgent4 = await rl.managedAgents.getSession({\n    session_id: sessionId,\n  });\n  if (['failed', 'cancelled'].includes(managedAgent4.status)) throw new Error('reached a terminal failure state: ' + managedAgent4.status);\n  if (['completed'].includes(managedAgent4.status)) break;\n  if (Date.now() > managedAgent4Deadline) throw new Error('timed out after 900000ms waiting for a terminal state');\n  await new Promise((resolve) => setTimeout(resolve, 10000));\n}\nconst sessionStatus = managedAgent4.status;\n\n// Read what the agent did\nconst managedAgent5 = await rl.managedAgents.listSessionEvents({\n  session_id: sessionId,\n});\nconst events = managedAgent5.events;",
+        },
+        cli: {
+            setup: '# Create the environment the agent works in\nENVIRONMENT_ID=$(rl managed-agents create-environment \\\n  --data "{ \\"description\\": \\"Sandbox for the quickstart research session.\\", \\"name\\": \\"Research sandbox\\", \\"provider\\": \\"runs\\" }" \\\n  | jq -r \'.environment_id\')\n\n# Create the agent\nAGENT_ID=$(rl managed-agents create-agent \\\n  --data "{ \\"model\\": \\"<gatewayModel>\\", \\"name\\": \\"Research assistant\\", \\"system\\": \\"Research the task, then write a concise report of what you found.\\" }" \\\n  | jq -r \'.agent_id\')',
+            main: '# Start a session\nSESSION_ID=$(rl managed-agents start-session \\\n  --data "{ \\"agent_id\\": \\"$AGENT_ID\\", \\"environment_id\\": \\"$ENVIRONMENT_ID\\", \\"message\\": \\"Write a one-paragraph summary of what a managed agent session is.\\" }" \\\n  | jq -r \'.session_id\')\n\n# Wait for the session to finish\ndeadline=$(( $(date +%s) + 900 ))\nwhile :; do\n  response=$(rl managed-agents get-session \\\n  --session_id "$SESSION_ID")\n  case "$(printf \'%s\' "$response" | jq -r \'.status\')" in failed|cancelled) echo "reached a terminal failure state: $response" >&2; exit 1 ;; esac\n  case "$(printf \'%s\' "$response" | jq -r \'.status\')" in completed) break ;; esac\n  [ "$(date +%s)" -ge "$deadline" ] && { echo "timed out waiting for a terminal state" >&2; exit 1; }\n  sleep 10\ndone\nSESSION_STATUS=$(printf \'%s\' "$response" | jq -r \'.status\')\n\n# Read what the agent did\nEVENTS=$(rl managed-agents list-session-events \\\n  --session_id "$SESSION_ID" \\\n  | jq -r \'.events\')',
+        },
+        curl: {
+            setup: '# Create the environment the agent works in\nENVIRONMENT_ID=$(curl -s -X POST "https://api.recursion.labelbox.com/managed-agents/v1/environments" \\\n  -H "Authorization: Bearer $LABELBOX_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d "{ \\"description\\": \\"Sandbox for the quickstart research session.\\", \\"name\\": \\"Research sandbox\\", \\"provider\\": \\"runs\\" }" \\\n  | jq -r \'.environment_id\')\n\n# Create the agent\nAGENT_ID=$(curl -s -X POST "https://api.recursion.labelbox.com/managed-agents/v1/agents" \\\n  -H "Authorization: Bearer $LABELBOX_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d "{ \\"model\\": \\"<gatewayModel>\\", \\"name\\": \\"Research assistant\\", \\"system\\": \\"Research the task, then write a concise report of what you found.\\" }" \\\n  | jq -r \'.agent_id\')',
+            main: '# Start a session\nSESSION_ID=$(curl -s -X POST "https://api.recursion.labelbox.com/managed-agents/v1/sessions" \\\n  -H "Authorization: Bearer $LABELBOX_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d "{ \\"agent_id\\": \\"$AGENT_ID\\", \\"environment_id\\": \\"$ENVIRONMENT_ID\\", \\"message\\": \\"Write a one-paragraph summary of what a managed agent session is.\\" }" \\\n  | jq -r \'.session_id\')\n\n# Wait for the session to finish\ndeadline=$(( $(date +%s) + 900 ))\nwhile :; do\n  response=$(curl -s -X GET "https://api.recursion.labelbox.com/managed-agents/v1/sessions/$SESSION_ID" \\\n  -H "Authorization: Bearer $LABELBOX_API_KEY")\n  case "$(printf \'%s\' "$response" | jq -r \'.status\')" in failed|cancelled) echo "reached a terminal failure state: $response" >&2; exit 1 ;; esac\n  case "$(printf \'%s\' "$response" | jq -r \'.status\')" in completed) break ;; esac\n  [ "$(date +%s)" -ge "$deadline" ] && { echo "timed out waiting for a terminal state" >&2; exit 1; }\n  sleep 10\ndone\nSESSION_STATUS=$(printf \'%s\' "$response" | jq -r \'.status\')\n\n# Read what the agent did\nEVENTS=$(curl -s -X GET "https://api.recursion.labelbox.com/managed-agents/v1/sessions/$SESSION_ID/events" \\\n  -H "Authorization: Bearer $LABELBOX_API_KEY" \\\n  | jq -r \'.events\')',
+        },
+        related: {
+            learnMore: [
+                {
+                    type: 'resource',
+                    id: 'managed-agents',
+                },
+            ],
+        },
+    },
     'run-an-evaluation': {
         id: 'run-an-evaluation',
         title: 'Run an evaluation',

package/dist/reference/recipes-schema.js

@@ -129,7 +129,7 @@ export const RecipeManifestSchema = z
     // One-sentence statement of the user goal this recipe accomplishes.
     goal: z.string().min(1),
     // The canonical product domain this recipe lives under in the docs How-to nav
-    // (one of the eight `DOMAINS`). Kebab here; membership in `DOMAINS` is enforced
+    // (one of the canonical `DOMAINS`). Kebab here; membership in `DOMAINS` is enforced
     // fail-fast by `recipes:generate` (it can't import the domains module — schema
     // files are loaded as source at codegen time, so they may only import npm deps).
     category: z.string().regex(KEBAB_CASE, 'category must be kebab-case'),

package/dist/reference/resources-reference.generated.js

@@ -2671,7 +2671,7 @@ export const RESOURCE_REFERENCE = {
                             name: 'reasoning_effort',
                             required: false,
                             type: 'string',
-                            description: 'Thinking-budget hint for reasoning-capable models, e.g. low, medium, or high. Ignored by models that do not support reasoning.',
+                            description: "Provider-native reasoning depth value. For gateway models, use one of supported_reasoning_efforts from the models catalog; omit it to follow the provider's current default.",
                         },
                         {
                             name: 'response_format',

package/dist/reference/sdk-reference.generated.js

@@ -44872,7 +44872,7 @@ export const SDK_REFERENCE = {
         cliExample: "rl managed-agents create-agent \\\n  --name 'example-name' \\\n  --system 'example' \\\n  --from-json body.json",
         curlExample: 'curl -X POST \'https://api.recursion.labelbox.com/managed-agents/v1/agents\' \\\n  -H \'Authorization: Bearer $LABELBOX_API_KEY\' \\\n  -H \'Content-Type: application/json\' \\\n  -d \'{\n    "custom_tools": [\n      {\n        "config": {\n          "key": "example"\n        },\n        "name": "example-name",\n        "type": "example"\n      }\n    ],\n    "default_credential_refs": [\n      {\n        "credential_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n        "vault_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d"\n      }\n    ],\n    "default_rubric": "example",\n    "default_vault_ids": [\n      "example"\n    ],\n    "description": "example",\n    "mcp_servers": [\n      {\n        "key": "example"\n      }\n    ],\n    "metadata": {\n      "key": "example"\n    },\n    "model": "example",\n    "model_config": {\n      "max_tokens": 1,\n      "provider_params": {\n        "key": "example"\n      },\n      "reasoning_effort": "example",\n      "response_format": "example",\n      "temperature": 1.5,\n      "tool_choice": "example",\n      "top_p": 1.5\n    },\n    "model_ref_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n    "multiagent": {\n      "key": "example"\n    },\n    "name": "example-name",\n    "runtime_adapters": [\n      {\n        "key": "example"\n      }\n    ],\n    "skills": [\n      {\n        "key": "example"\n      }\n    ],\n    "system": "example",\n    "tools": [\n      {\n        "config": {\n          "key": "example"\n        },\n        "name": "example-name",\n        "type": "example"\n      }\n    ],\n    "toolsets": [\n      {\n        "config": {\n          "key": "example"\n        },\n        "name": "example-name",\n        "type": "example"\n      }\n    ],\n    "web_search_enabled": true\n  }\'',
         summary: 'Create an agent and immutable version',
-        description: 'Creates an agent and its first immutable version, and returns the agent resolved to that version. Exactly one of model or model_ref_id is required alongside name and system. The body is also accepted as application/x-yaml with the same schema. Any vault named in default_vault_ids must already exist.',
+        description: 'Creates an agent and its first immutable version, and returns the agent resolved to that version. Exactly one of model or model_ref_id is required alongside name and system. The body is also accepted as application/x-yaml with the same schema. Any vault named in default_vault_ids must already exist. Invalid model_config and unsupported reasoning_effort values return 400, including when a reachable gateway model publishes no exact options; an unconfigured or unreachable gateway that prevents verification returns 503.',
         httpMethod: 'post',
         path: '/managed-agents/v1/agents',
         requiredPermissions: ['managed-agents:create'],
@@ -44980,7 +44980,7 @@ export const SDK_REFERENCE = {
                 in: 'body',
                 required: false,
                 type: 'ManagedAgentsInferenceConfig',
-                description: 'Default inference config applied to sessions started from this agent.',
+                description: "Default inference config applied to sessions started from this agent. Omit model_config or send {} to use provider defaults; null is invalid. reasoning_effort is normalized and validated for direct providers, and must exactly match the selected gateway model's published options. An unsupported value, including a reachable gateway model that publishes no exact options, returns 400; an unconfigured or unreachable gateway that prevents verification returns 503.",
                 fields: [
                     {
                         name: 'max_tokens',
@@ -44999,7 +44999,7 @@ export const SDK_REFERENCE = {
                         name: 'reasoning_effort',
                         required: false,
                         type: 'string',
-                        description: 'Thinking-budget hint for reasoning-capable models, e.g. low, medium, or high. Ignored by models that do not support reasoning.',
+                        description: "Provider-native reasoning depth value. For gateway models, use one of supported_reasoning_efforts from the models catalog; omit it to follow the provider's current default.",
                     },
                     {
                         name: 'response_format',
@@ -45234,7 +45234,7 @@ export const SDK_REFERENCE = {
                             name: 'reasoning_effort',
                             required: false,
                             type: 'string',
-                            description: 'Thinking-budget hint for reasoning-capable models, e.g. low, medium, or high. Ignored by models that do not support reasoning.',
+                            description: "Provider-native reasoning depth value. For gateway models, use one of supported_reasoning_efforts from the models catalog; omit it to follow the provider's current default.",
                         },
                         {
                             name: 'response_format',
@@ -48639,7 +48639,7 @@ export const SDK_REFERENCE = {
                             name: 'reasoning_effort',
                             required: false,
                             type: 'string',
-                            description: 'Thinking-budget hint for reasoning-capable models, e.g. low, medium, or high. Ignored by models that do not support reasoning.',
+                            description: "Provider-native reasoning depth value. For gateway models, use one of supported_reasoning_efforts from the models catalog; omit it to follow the provider's current default.",
                         },
                         {
                             name: 'response_format',
@@ -49025,7 +49025,7 @@ export const SDK_REFERENCE = {
                             name: 'reasoning_effort',
                             required: false,
                             type: 'string',
-                            description: 'Thinking-budget hint for reasoning-capable models, e.g. low, medium, or high. Ignored by models that do not support reasoning.',
+                            description: "Provider-native reasoning depth value. For gateway models, use one of supported_reasoning_efforts from the models catalog; omit it to follow the provider's current default.",
                         },
                         {
                             name: 'response_format',
@@ -55184,7 +55184,7 @@ export const SDK_REFERENCE = {
         cliExample: "rl managed-agents start-session \\\n  --agent_id '9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d' \\\n  --environment_id '9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d' \\\n  --from-json body.json",
         curlExample: 'curl -X POST \'https://api.recursion.labelbox.com/managed-agents/v1/sessions\' \\\n  -H \'Authorization: Bearer $LABELBOX_API_KEY\' \\\n  -H \'Content-Type: application/json\' \\\n  -d \'{\n    "agent_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n    "credential_refs": [\n      {\n        "credential_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n        "vault_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d"\n      }\n    ],\n    "environment_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n    "external_source_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n    "external_source_type": "example",\n    "idempotency_key": "example",\n    "message": "example",\n    "metadata": {\n      "key": "example"\n    },\n    "outcome": {\n      "description": "example",\n      "grader_model_ref_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n      "max_iterations": 1,\n      "rubric": "example"\n    },\n    "project_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n    "skip_default_outcome": true,\n    "vault_ids": [\n      "example"\n    ]\n  }\'',
         summary: 'Start a managed session',
-        description: 'Starts a managed agent session and returns 202 with its session_id and status_path; the agent runs asynchronously, so poll getSession or subscribe with streamSessionEvents to follow it. Sandbox compute is provisioned here, which is where a session begins costing money. Send an Idempotency-Key header to make retries safe: the same key with the same body returns the original session, and with a different body is rejected.',
+        description: 'Starts a managed agent session and returns 202 with its session_id and status_path; the agent runs asynchronously, so poll getSession or subscribe with streamSessionEvents to follow it. Sandbox compute is provisioned here, which is where a session begins costing money. Send an Idempotency-Key header to make retries safe: the same key with the same body returns the original session, and with a different body is rejected. A reasoning_effort incompatible with the selected model or its frozen output capacity returns 400 before provisioning; a temporarily unavailable model reference or catalog dependency returns 503.',
         httpMethod: 'post',
         path: '/managed-agents/v1/sessions',
         requiredPermissions: ['managed-agents:create'],
@@ -55351,7 +55351,7 @@ export const SDK_REFERENCE = {
         cliExample: 'rl managed-agents update-agent \\\n  --agent_id <agent_id> \\\n  --from-json body.json',
         curlExample: 'curl -X PATCH \'https://api.recursion.labelbox.com/managed-agents/v1/agents/<agent_id>\' \\\n  -H \'Authorization: Bearer $LABELBOX_API_KEY\' \\\n  -H \'Content-Type: application/json\' \\\n  -d \'{\n    "agent_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n    "created_at": "2026-02-18T09:30:00Z",\n    "custom_tools": [\n      {\n        "config": {\n          "key": "example"\n        },\n        "name": "example-name",\n        "type": "example"\n      }\n    ],\n    "default_credential_refs": [\n      {\n        "credential_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n        "vault_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d"\n      }\n    ],\n    "default_rubric": "example",\n    "default_vault_ids": [\n      "example"\n    ],\n    "description": "example",\n    "latest_agent_version_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n    "mcp_servers": [\n      {\n        "key": "example"\n      }\n    ],\n    "metadata": {\n      "key": "example"\n    },\n    "model": "example",\n    "model_config": {\n      "max_tokens": 1,\n      "provider_params": {\n        "key": "example"\n      },\n      "reasoning_effort": "example",\n      "response_format": "example",\n      "temperature": 1.5,\n      "tool_choice": "example",\n      "top_p": 1.5\n    },\n    "model_ref_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n    "multiagent": {\n      "key": "example"\n    },\n    "name": "example-name",\n    "organization_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n    "runtime_adapters": [\n      {\n        "key": "example"\n      }\n    ],\n    "skills": [\n      {\n        "key": "example"\n      }\n    ],\n    "system": "example",\n    "toolsets": [\n      {\n        "config": {\n          "key": "example"\n        },\n        "name": "example-name",\n        "type": "example"\n      }\n    ],\n    "updated_at": "2026-02-18T09:30:00Z",\n    "web_search_enabled": true\n  }\'',
         summary: 'Update agent and create a new immutable version',
-        description: 'Applies a partial update and returns the agent resolved to the new version. Agent versions are immutable, so every accepted update mints a new one rather than editing history; omitted fields keep their current values. Running sessions keep the version they started with.',
+        description: 'Applies a partial update and returns the agent resolved to the new version. Agent versions are immutable, so every accepted update mints a new one rather than editing history; omitted fields keep their current values. Running sessions keep the version they started with. Invalid model_config and unsupported new or changed reasoning_effort values return 400, including when a reachable gateway model publishes no exact options; an unconfigured or unreachable gateway that prevents verification returns 503.',
         httpMethod: 'patch',
         path: '/managed-agents/v1/agents/{agent_id}',
         requiredPermissions: ['managed-agents:update'],
@@ -55447,7 +55447,7 @@ export const SDK_REFERENCE = {
                 in: 'body',
                 required: false,
                 type: 'ManagedAgentsInferenceConfig',
-                description: 'Default inference settings applied to every turn unless a session overrides them.',
+                description: "Default inference config for the new version. Omit model_config to preserve the current config; send {} to clear the entire config and use provider defaults; null is invalid. reasoning_effort is normalized and validated for direct providers, and must exactly match the selected gateway model's published options. An unsupported new or changed value, including a reachable gateway model that publishes no exact options, returns 400; an unconfigured or unreachable gateway that prevents verification returns 503.",
                 fields: [
                     {
                         name: 'max_tokens',
@@ -55466,7 +55466,7 @@ export const SDK_REFERENCE = {
                         name: 'reasoning_effort',
                         required: false,
                         type: 'string',
-                        description: 'Thinking-budget hint for reasoning-capable models, e.g. low, medium, or high. Ignored by models that do not support reasoning.',
+                        description: "Provider-native reasoning depth value. For gateway models, use one of supported_reasoning_efforts from the models catalog; omit it to follow the provider's current default.",
                     },
                     {
                         name: 'response_format',
@@ -55661,7 +55661,7 @@ export const SDK_REFERENCE = {
                             name: 'reasoning_effort',
                             required: false,
                             type: 'string',
-                            description: 'Thinking-budget hint for reasoning-capable models, e.g. low, medium, or high. Ignored by models that do not support reasoning.',
+                            description: "Provider-native reasoning depth value. For gateway models, use one of supported_reasoning_efforts from the models catalog; omit it to follow the provider's current default.",
                         },
                         {
                             name: 'response_format',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@labelbox/recursion-sdk",
-  "version": "0.0.165",
+  "version": "0.0.167",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",