@labelbox/recursion-sdk 0.0.165 → 0.0.166

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/package.json

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