> ## 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.

# TypeScript SDK

> Use the Asteroid TypeScript SDK to execute agents, monitor runs, and manage profiles

Use the `asteroid-odyssey` TypeScript SDK to execute agents, monitor executions, work with files, and manage profiles from your application.

<Info>
  The SDK exports a `client` singleton and individual endpoint functions. Configure the client once with your API key, then call the functions directly.
</Info>

## Install

```bash theme={null}
npm install asteroid-odyssey
```

Or with pnpm:

```bash theme={null}
pnpm add asteroid-odyssey
```

## Quickstart

```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: {
      customerName: 'Jane Doe',
    },
    metadata: {
      source: 'docs',
    },
  },
});

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

// Poll until complete
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);
```

Run it with:

```bash theme={null}
npx tsx run_agent.ts
```

## Client Configuration

All SDK functions share the singleton `client`. Configure it once at startup:

```ts theme={null}
import { client } from 'asteroid-odyssey';

client.setConfig({
  headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
  // Optional: override the base URL
  baseUrl: 'https://odyssey.asteroid.ai/agents/v2',
});
```

Every function accepts an optional `client` override if you need per-request auth:

```ts theme={null}
const { data } = await executionGet({
  client: myOtherClient,
  path: { executionId },
});
```

## Exported Functions

| Function                      | Purpose                                         |
| ----------------------------- | ----------------------------------------------- |
| `agentList`                   | List agents with pagination                     |
| `agentExecutePost`            | Execute an agent                                |
| `executionGet`                | Fetch execution details                         |
| `executionsList`              | List executions with filters                    |
| `executionActivitiesGet`      | Fetch execution activities (returns `Array`)    |
| `executionStatusUpdate`       | Update execution status (e.g. cancel)           |
| `executionUserMessagesAdd`    | Send a user message to a running execution      |
| `executionContextFilesGet`    | List files on an execution                      |
| `executionContextFilesUpload` | Upload files to a running execution             |
| `tempFilesStage`              | Stage temporary files before execution          |
| `agentProfilesList`           | List agent profiles (requires `organizationId`) |
| `agentProfilesCreate`         | Create an agent profile                         |
| `agentProfileGet`             | Fetch a single profile                          |
| `agentProfileUpdate`          | Update a profile                                |
| `agentProfileDelete`          | Delete a profile                                |
| `agentWorkflowsExecute`       | Execute a specific workflow version             |

## Common Patterns

<Tabs>
  <Tab title="Executions">
    ```ts theme={null}
    import {
      client,
      agentExecutePost,
      executionsList,
      executionActivitiesGet,
      executionUserMessagesAdd,
    } from 'asteroid-odyssey';

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

    const { data } = await agentExecutePost({
      path: { agentId: 'your-agent-id' },
      body: {
        inputs: {
          task: 'Summarize the attached invoice',
        },
      },
    });
    const executionId = data!.executionId;

    const { data: page } = await executionsList({
      query: {
        page: 1,
        pageSize: 10,
        executionId,
      },
    });

    const { data: activities } = await executionActivitiesGet({
      path: { executionId },
      query: { limit: 20, order: 'desc' },
    });

    await executionUserMessagesAdd({
      path: { executionId },
      body: { message: 'Please use the latest file only.' },
    });

    console.log(page?.items);
    console.log(activities?.map((a) => a.payload.activityType));
    ```
  </Tab>

  <Tab title="Files">
    ```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 fileBuffer = readFileSync('./invoice.pdf');
    const invoice = new File([fileBuffer], 'invoice.pdf', { type: 'application/pdf' });

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

    const { data } = await agentExecutePost({
      path: { agentId: 'your-agent-id' },
      body: {
        inputs: { task: 'Read the staged file' },
        tempFiles: staged?.tempFiles,
      },
    });
    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()));
    }
    ```
  </Tab>

  <Tab title="Profiles">
    ```ts theme={null}
    import {
      client,
      agentProfilesList,
      agentProfilesCreate,
      agentProfileUpdate,
    } from 'asteroid-odyssey';

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

    const { data: profiles } = await agentProfilesList({
      query: { organizationId: 'your-org-id', page: 1, pageSize: 20 },
    });
    console.log(profiles?.items?.map((p) => `${p.id}: ${p.name}`));

    const { data: created } = await agentProfilesCreate({
      body: {
        name: 'Shared Billing Profile',
        description: 'Reusable browser profile for billing workflows',
        organizationId: 'your-org-id',
        proxyCountryCode: 'us',
        proxyType: 'residential',
        captchaSolverActive: false,
        stickyIp: false,
        credentials: [],
        cookies: [],
      },
    });

    await agentProfileUpdate({
      path: { profileId: created!.id },
      body: { description: 'Updated description' },
    });
    ```
  </Tab>
</Tabs>

## Notes

* Use `inputs` for execution variables — `dynamicData` is deprecated.
* `executionActivitiesGet` returns `Array<AgentsExecutionActivity>` directly, not a wrapped object.
* `agentProfilesList` requires `organizationId` in the query.
* All functions return `{ data, error }`. Check `error` before using `data`.
* File list responses include a `downloadUrl` per file. Fetch it with your API key in the `X-Asteroid-Agents-Api-Key` header.

## Related Resources

<CardGroup cols={2}>
  <Card title="Python SDK" icon="terminal" href="/sdks/python">
    See the Python SDK guide
  </Card>

  <Card title="API" icon="book" href="/api-reference/overview">
    Browse the API landing page and common workflows
  </Card>
</CardGroup>