@labelbox/recursion-sdk 0.0.164 → 0.0.166

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

@@ -562,6 +562,7 @@ export declare class ManagedAgents extends HeyApiClient {
         after_event_id?: string;
         limit?: number;
         hydrate?: 'images';
+        image_urls?: 'signed';
         payloads?: 'refs';
     }, options?: Options<never, ThrowOnError>): import("./client/types.gen.js").RequestResult<GetManagedAgentsV1SessionsBySessionIdEventsResponses, GetManagedAgentsV1SessionsBySessionIdEventsErrors, ThrowOnError, "data">;
     /**
@@ -646,6 +647,7 @@ export declare class ManagedAgents extends HeyApiClient {
     getSessionTree<ThrowOnError extends boolean = false>(parameters: {
         session_id: string;
         hydrate?: 'images';
+        image_urls?: 'signed';
         payloads?: 'refs';
     }, options?: Options<never, ThrowOnError>): import("./client/types.gen.js").RequestResult<GetManagedAgentsV1SessionsBySessionIdTreeResponses, GetManagedAgentsV1SessionsBySessionIdTreeErrors, ThrowOnError, "data">;
     /**

package/dist/generated/sdk.gen.js

@@ -1068,6 +1068,7 @@ export class ManagedAgents extends HeyApiClient {
                     { in: 'query', key: 'after_event_id' },
                     { in: 'query', key: 'limit' },
                     { in: 'query', key: 'hydrate' },
+                    { in: 'query', key: 'image_urls' },
                     { in: 'query', key: 'payloads' }
                 ] }]);
         return (options?.client ?? this.client).get({
@@ -1229,6 +1230,7 @@ export class ManagedAgents extends HeyApiClient {
         const params = buildClientParams([parameters], [{ args: [
                     { in: 'path', key: 'session_id' },
                     { in: 'query', key: 'hydrate' },
+                    { in: 'query', key: 'image_urls' },
                     { in: 'query', key: 'payloads' }
                 ] }]);
         return (options?.client ?? this.client).get({

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

@@ -8130,6 +8130,14 @@ export type ManagedAgentsContentBlock = {
      * Private typed content reference. Fetch through the authenticated session image proxy; clients cannot read this gs:// URI directly.
      */
     uri?: string;
+    /**
+     * Short-lived HTTPS URL for the image bytes. Present only when the read asked for image_urls=signed and the deployment has signing configured. Never stored; fetch a fresh read after url_expires_at.
+     */
+    url?: string;
+    /**
+     * When url stops working. Absent whenever url is.
+     */
+    url_expires_at?: unknown;
     /**
      * Validated image width in pixels.
      */
@@ -26727,6 +26735,10 @@ export type GetManagedAgentsV1SessionsBySessionIdEventsData = {
          * Opt-in compatibility mode. images rehydrates private image refs under strict response caps; omitted by default.
          */
         hydrate?: 'images';
+        /**
+         * Set to signed to add a short-lived url (and url_expires_at) to every stored image block the caller may read. Omitted when the deployment has no URL signing configured; the authenticated /images proxy always works.
+         */
+        image_urls?: 'signed';
         /**
          * External event payloads hydrate by default. Set refs to return bounded stubs and private reference metadata only.
          */
@@ -27230,6 +27242,10 @@ export type GetManagedAgentsV1SessionsBySessionIdTreeData = {
          * Opt-in compatibility mode. images rehydrates private image refs under strict response caps; omitted by default.
          */
         hydrate?: 'images';
+        /**
+         * Set to signed to add a short-lived url (and url_expires_at) to every stored image block the caller may read. Omitted when the deployment has no URL signing configured; the authenticated /images proxy always works.
+         */
+        image_urls?: 'signed';
         /**
          * External event payloads hydrate by default. Set refs to return bounded stubs and private reference metadata only.
          */

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/sdk-reference.generated.js

@@ -51960,7 +51960,7 @@ export const SDK_REFERENCE = {
         namespace: 'managedAgents',
         method: 'getSessionTree',
         signature: 'rl.managedAgents.getSessionTree({ session_id })',
-        example: "const result = await rl.managedAgents.getSessionTree({\n  session_id: '<session_id>',\n  // optional: hydrate, payloads\n});",
+        example: "const result = await rl.managedAgents.getSessionTree({\n  session_id: '<session_id>',\n  // optional: hydrate, image_urls, payloads\n});",
         cliInvocation: 'rl managed-agents get-session-tree',
         cliExample: 'rl managed-agents get-session-tree \\\n  --session_id <session_id>',
         curlExample: "curl -X GET 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/<session_id>/tree' \\\n  -H 'Authorization: Bearer $LABELBOX_API_KEY'",
@@ -51978,6 +51978,14 @@ export const SDK_REFERENCE = {
                 description: 'Opt-in compatibility mode. images rehydrates private image refs under strict response caps; omitted by default.',
                 enum: ['images'],
             },
+            {
+                name: 'image_urls',
+                in: 'query',
+                required: false,
+                type: 'string',
+                description: 'Set to signed to add a short-lived url (and url_expires_at) to every stored image block the caller may read. Omitted when the deployment has no URL signing configured; the authenticated /images proxy always works.',
+                enum: ['signed'],
+            },
             {
                 name: 'payloads',
                 in: 'query',
@@ -53397,7 +53405,7 @@ export const SDK_REFERENCE = {
         namespace: 'managedAgents',
         method: 'listSessionEvents',
         signature: 'rl.managedAgents.listSessionEvents({ session_id })',
-        example: "const result = await rl.managedAgents.listSessionEvents({\n  session_id: '<session_id>',\n  // optional: after_event_id, limit, hydrate, payloads\n});",
+        example: "const result = await rl.managedAgents.listSessionEvents({\n  session_id: '<session_id>',\n  // optional: after_event_id, limit, hydrate, image_urls, payloads\n});",
         cliInvocation: 'rl managed-agents list-session-events',
         cliExample: 'rl managed-agents list-session-events \\\n  --session_id <session_id>',
         curlExample: "curl -X GET 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/<session_id>/events' \\\n  -H 'Authorization: Bearer $LABELBOX_API_KEY'",
@@ -53429,6 +53437,14 @@ export const SDK_REFERENCE = {
                 description: 'Opt-in compatibility mode. images rehydrates private image refs under strict response caps; omitted by default.',
                 enum: ['images'],
             },
+            {
+                name: 'image_urls',
+                in: 'query',
+                required: false,
+                type: 'string',
+                description: 'Set to signed to add a short-lived url (and url_expires_at) to every stored image block the caller may read. Omitted when the deployment has no URL signing configured; the authenticated /images proxy always works.',
+                enum: ['signed'],
+            },
             {
                 name: 'payloads',
                 in: 'query',
@@ -54887,10 +54903,10 @@ export const SDK_REFERENCE = {
         method: 'sendSessionEvents',
         bodyKey: 'body',
         signature: 'rl.managedAgents.sendSessionEvents({ session_id, body })',
-        example: 'const result = await rl.managedAgents.sendSessionEvents({\n  session_id: \'<session_id>\',\n  body: {\n    actor: "human:api",\n    events: [\n      {\n        actor: "human:api",\n        content: [\n          {\n            byte_size: 1,\n            content: [],\n            data: "example",\n            encrypted_content: "example",\n            height: 1,\n            id: "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n            input: {\n              key: "example"\n            },\n            is_error: true,\n            media_type: "example",\n            name: "example-name",\n            omitted_bytes: 1,\n            payload: "example",\n            provider: "example",\n            provider_payload: "example",\n            redacted: true,\n            semantic_hint: "example",\n            sha256: "example",\n            signature: "example",\n            summary: [],\n            text: "example",\n            tool_use_id: "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n            type: "example",\n            uri: "example",\n            width: 1\n          }\n        ],\n        text: "example",\n        type: "user.message"\n      }\n    ],\n    message: "example"\n  },\n});',
+        example: 'const result = await rl.managedAgents.sendSessionEvents({\n  session_id: \'<session_id>\',\n  body: {\n    actor: "human:api",\n    events: [\n      {\n        actor: "human:api",\n        content: [\n          {\n            byte_size: 1,\n            content: [],\n            data: "example",\n            encrypted_content: "example",\n            height: 1,\n            id: "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n            input: {\n              key: "example"\n            },\n            is_error: true,\n            media_type: "example",\n            name: "example-name",\n            omitted_bytes: 1,\n            payload: "example",\n            provider: "example",\n            provider_payload: "example",\n            redacted: true,\n            semantic_hint: "example",\n            sha256: "example",\n            signature: "example",\n            summary: [],\n            text: "example",\n            tool_use_id: "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n            type: "example",\n            uri: "example",\n            url: "https://example.com",\n            url_expires_at: "2026-02-18T09:30:00Z",\n            width: 1\n          }\n        ],\n        text: "example",\n        type: "user.message"\n      }\n    ],\n    message: "example"\n  },\n});',
         cliInvocation: 'rl managed-agents send-session-events',
         cliExample: 'rl managed-agents send-session-events \\\n  --session_id <session_id> \\\n  --from-json body.json',
-        curlExample: 'curl -X POST \'https://api.recursion.labelbox.com/managed-agents/v1/sessions/<session_id>/events\' \\\n  -H \'Authorization: Bearer $LABELBOX_API_KEY\' \\\n  -H \'Content-Type: application/json\' \\\n  -d \'{\n    "actor": "human:api",\n    "events": [\n      {\n        "actor": "human:api",\n        "content": [\n          {\n            "byte_size": 1,\n            "content": [],\n            "data": "example",\n            "encrypted_content": "example",\n            "height": 1,\n            "id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n            "input": {\n              "key": "example"\n            },\n            "is_error": true,\n            "media_type": "example",\n            "name": "example-name",\n            "omitted_bytes": 1,\n            "payload": "example",\n            "provider": "example",\n            "provider_payload": "example",\n            "redacted": true,\n            "semantic_hint": "example",\n            "sha256": "example",\n            "signature": "example",\n            "summary": [],\n            "text": "example",\n            "tool_use_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n            "type": "example",\n            "uri": "example",\n            "width": 1\n          }\n        ],\n        "text": "example",\n        "type": "user.message"\n      }\n    ],\n    "message": "example"\n  }\'',
+        curlExample: 'curl -X POST \'https://api.recursion.labelbox.com/managed-agents/v1/sessions/<session_id>/events\' \\\n  -H \'Authorization: Bearer $LABELBOX_API_KEY\' \\\n  -H \'Content-Type: application/json\' \\\n  -d \'{\n    "actor": "human:api",\n    "events": [\n      {\n        "actor": "human:api",\n        "content": [\n          {\n            "byte_size": 1,\n            "content": [],\n            "data": "example",\n            "encrypted_content": "example",\n            "height": 1,\n            "id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n            "input": {\n              "key": "example"\n            },\n            "is_error": true,\n            "media_type": "example",\n            "name": "example-name",\n            "omitted_bytes": 1,\n            "payload": "example",\n            "provider": "example",\n            "provider_payload": "example",\n            "redacted": true,\n            "semantic_hint": "example",\n            "sha256": "example",\n            "signature": "example",\n            "summary": [],\n            "text": "example",\n            "tool_use_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n            "type": "example",\n            "uri": "example",\n            "url": "https://example.com",\n            "url_expires_at": "2026-02-18T09:30:00Z",\n            "width": 1\n          }\n        ],\n        "text": "example",\n        "type": "user.message"\n      }\n    ],\n    "message": "example"\n  }\'',
         summary: 'Append user/system events to a session',
         description: 'Appends user or system events to a session and returns how many were accepted. A running session is signalled so the agent wakes and sees them; once the workflow is gone the events are appended to the transcript instead, which the temporal_signaled field distinguishes. Events are appended in the order given. An omitted or empty events array yields exactly one user turn built from message; the request fails with 400 only when every entry sent was dropped, leaving nothing to append.',
         httpMethod: 'post',

package/package.json

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