> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteroid.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cookbook

> Practical examples for the current Asteroid TypeScript and Python SDKs

These examples are aligned with the current SDK surfaces documented on the [TypeScript SDK](/sdks/typescript) and [Python SDK](/sdks/python) pages.

<Tabs>
  <Tab title="Basic Execution" icon="play">
    Start an execution and poll until the result is available.

    <CodeGroup>
      ```ts theme={null}
      import { client, agentExecutePost, executionGet } from 'asteroid-odyssey';

      client.setConfig({
        headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
      });

      const { data, error } = await agentExecutePost({
        path: { agentId: 'your-agent-id' },
        body: {
          inputs: {
            patientName: 'Jane Doe',
            appointmentDate: '2026-03-27',
          },
          metadata: {
            source: 'cookbook-basic',
          },
        },
      });

      if (error) throw new Error(JSON.stringify(error));
      const executionId = data.executionId;

      let exec;
      do {
        await new Promise((r) => setTimeout(r, 3000));
        const res = await executionGet({ path: { executionId } });
        exec = res.data;
      } while (exec?.status === 'running' || exec?.status === 'starting');

      console.log(exec?.status, exec?.inputs);
      ```

      ```python theme={null}
      import os
      import time
      from asteroid_odyssey import Configuration, ApiClient
      from asteroid_odyssey.api.agents_api import AgentsApi
      from asteroid_odyssey.api.execution_api import ExecutionApi
      from asteroid_odyssey.models.agents_agent_execute_agent_request import AgentsAgentExecuteAgentRequest

      config = Configuration(api_key={"ApiKeyAuth": os.environ["ASTEROID_API_KEY"]})

      with ApiClient(config) as api_client:
          agents_api = AgentsApi(api_client)
          exec_api = ExecutionApi(api_client)

          response = agents_api.agent_execute_post(
              agent_id="your-agent-id",
              agents_agent_execute_agent_request=AgentsAgentExecuteAgentRequest(
                  inputs={
                      "patientName": "Jane Doe",
                      "appointmentDate": "2026-03-27",
                  },
              ),
          )
          execution_id = response.execution_id

          while True:
              time.sleep(3)
              execution = exec_api.execution_get(execution_id=execution_id)
              if execution.status not in ("running", "starting"):
                  break

          print(execution.status, execution.inputs)
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Interactive Run" icon="message">
    Handle runs that pause and need a user message before they can continue.

    <CodeGroup>
      ```ts theme={null}
      import {
        client,
        agentExecutePost,
        executionGet,
        executionUserMessagesAdd,
      } from 'asteroid-odyssey';

      client.setConfig({
        headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
      });

      const { data, error } = await agentExecutePost({
        path: { agentId: 'your-agent-id' },
        body: {
          inputs: {
            task: 'Ask the user to confirm before submitting the final form',
          },
        },
      });
      if (error) throw new Error(JSON.stringify(error));
      const executionId = data.executionId;

      // Wait for the agent to pause for input
      let exec;
      do {
        await new Promise((r) => setTimeout(r, 3000));
        const res = await executionGet({ path: { executionId } });
        exec = res.data;
      } while (exec?.status === 'running' || exec?.status === 'starting');

      if (exec?.status === 'paused_by_agent') {
        await executionUserMessagesAdd({
          path: { executionId },
          body: { message: 'Confirmed. Please continue.' },
        });
      }

      // Continue polling until terminal state
      do {
        await new Promise((r) => setTimeout(r, 3000));
        const res = await executionGet({ path: { executionId } });
        exec = res.data;
      } while (exec?.status === 'running' || exec?.status === 'paused_by_agent');

      console.log(exec?.status);
      ```

      ```python theme={null}
      import os
      import time
      from asteroid_odyssey import Configuration, ApiClient
      from asteroid_odyssey.api.agents_api import AgentsApi
      from asteroid_odyssey.api.execution_api import ExecutionApi
      from asteroid_odyssey.models.agents_agent_execute_agent_request import AgentsAgentExecuteAgentRequest

      config = Configuration(api_key={"ApiKeyAuth": os.environ["ASTEROID_API_KEY"]})

      with ApiClient(config) as api_client:
          agents_api = AgentsApi(api_client)
          exec_api = ExecutionApi(api_client)

          response = agents_api.agent_execute_post(
              agent_id="your-agent-id",
              agents_agent_execute_agent_request=AgentsAgentExecuteAgentRequest(
                  inputs={"task": "Ask the user to confirm before submitting the final form"},
              ),
          )
          execution_id = response.execution_id

          # Poll until paused or terminal
          while True:
              time.sleep(3)
              execution = exec_api.execution_get(execution_id=execution_id)
              if execution.status not in ("running", "starting"):
                  break

          if execution.status == "paused_by_agent":
              exec_api.execution_user_messages_add(
                  execution_id=execution_id,
                  agents_execution_user_messages_add_text_body={"message": "Confirmed. Please continue."},
              )

              # Poll until terminal
              while True:
                  time.sleep(3)
                  execution = exec_api.execution_get(execution_id=execution_id)
                  if execution.status not in ("running", "paused_by_agent"):
                      break

          print(execution.status)
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Files" icon="file">
    Attach files to executions and download the files produced by a run.

    <CodeGroup>
      ```ts theme={null}
      import {
        client,
        agentExecutePost,
        tempFilesStage,
        executionContextFilesUpload,
        executionContextFilesGet,
      } from 'asteroid-odyssey';
      import { readFileSync, writeFileSync } from 'node:fs';

      client.setConfig({
        headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
      });

      const invoiceBytes = readFileSync('./invoice.pdf');
      const invoice = new File([invoiceBytes], 'invoice.pdf', { type: 'application/pdf' });

      const { data: staged } = await tempFilesStage({
        path: { organizationId: 'your-org-id' },
        body: { files: [invoice] },
      });

      const { data, error } = await agentExecutePost({
        path: { agentId: 'your-agent-id' },
        body: {
          inputs: {
            task: 'Read the attached invoice and summarize it',
          },
          tempFiles: staged?.tempFiles,
        },
      });
      if (error) throw new Error(JSON.stringify(error));
      const executionId = data.executionId;

      await executionContextFilesUpload({
        path: { executionId },
        body: { files: [invoice] },
      });

      const { data: files } = await executionContextFilesGet({
        path: { executionId },
      });
      for (const file of files ?? []) {
        const response = await fetch(file.downloadUrl, {
          headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
        });
        if (!response.ok) throw new Error(`Download failed: ${response.status}`);
        writeFileSync(`./downloads/${file.fileName}`, Buffer.from(await response.arrayBuffer()));
      }
      ```

      ```python theme={null}
      import os
      from asteroid_odyssey import Configuration, ApiClient
      from asteroid_odyssey.api.agents_api import AgentsApi
      from asteroid_odyssey.api.files_api import FilesApi
      from asteroid_odyssey.models.agents_agent_execute_agent_request import AgentsAgentExecuteAgentRequest

      config = Configuration(api_key={"ApiKeyAuth": os.environ["ASTEROID_API_KEY"]})

      with ApiClient(config) as api_client:
          agents_api = AgentsApi(api_client)
          files_api = FilesApi(api_client)

          response = agents_api.agent_execute_post(
              agent_id="your-agent-id",
              agents_agent_execute_agent_request=AgentsAgentExecuteAgentRequest(
                  inputs={"task": "Read the uploaded invoice and summarize it"},
              ),
          )
          execution_id = response.execution_id

          files_api.execution_context_files_upload(
              execution_id=execution_id,
              files=[open("./invoice.pdf", "rb")],
          )

          files = files_api.execution_context_files_get(execution_id=execution_id)
          for file in files:
              print(f"{file.file_name}: {file.file_size} bytes")
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Related Resources

<CardGroup cols={2}>
  <Card title="TypeScript SDK" icon="code" href="/sdks/typescript">
    See the current TypeScript helper and generated namespaces
  </Card>

  <Card title="Python SDK" icon="terminal" href="/sdks/python">
    See the current Python high-level client and generated subpackages
  </Card>
</CardGroup>