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 and Python SDK pages.

Basic Execution

Start an execution and poll until the result is available.

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);

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)

Interactive Run

Handle runs that pause and need a user message before they can continue.

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);

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)

Files

Attach files to executions and download the files produced by a run.

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}`);
  // Strip any path components from the server-provided name to avoid path traversal.
  const safeName = file.fileName.replace(/[/\\]/g, '_');
  writeFileSync(`./downloads/${safeName}`, Buffer.from(await response.arrayBuffer()));
}

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")

Related Resources

TypeScript SDK

See the current TypeScript helper and generated namespaces

Python SDK

See the current Python high-level client and generated subpackages