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

# Agents API

> Manage agents programmatically

# Agents API

The Agents API lets you list, create, deploy, and invoke agents.

Access via `client.agents`:

```typescript theme={null}
const client = new CastariClient({ apiKey: '...' });
const agents = client.agents;
```

## Methods

### list()

List all agents for the authenticated user.

```typescript theme={null}
const agents = await client.agents.list();
```

**Returns:** `Promise<Agent[]>`

**Example:**

```typescript theme={null}
const agents = await client.agents.list();

for (const agent of agents) {
  console.log(`${agent.name} (${agent.slug}) - ${agent.status}`);
}
```

***

### get(slug)

Get a specific agent by slug.

```typescript theme={null}
const agent = await client.agents.get(slug);
```

**Parameters:**

| Name   | Type     | Description             |
| ------ | -------- | ----------------------- |
| `slug` | `string` | The agent's unique slug |

**Returns:** `Promise<Agent>`

**Example:**

```typescript theme={null}
const agent = await client.agents.get('my-agent');
console.log(agent.status); // 'active'
```

**Errors:**

* `404` — Agent not found

***

### create(options)

Create a new agent.

```typescript theme={null}
const agent = await client.agents.create(options);
```

**Parameters:**

| Name                  | Type               | Required | Description                                                  |
| --------------------- | ------------------ | -------- | ------------------------------------------------------------ |
| `options.name`        | `string`           | Yes      | Display name for the agent                                   |
| `options.slug`        | `string`           | No       | Unique identifier (auto-generated from name if not provided) |
| `options.description` | `string`           | No       | Agent description                                            |
| `options.sourceType`  | `'git' \| 'local'` | No       | Source type (default: `'git'`)                               |
| `options.gitRepoUrl`  | `string`           | No       | Git repository URL (required when sourceType is `'git'`)     |

**Returns:** `Promise<Agent>`

**Example:**

```typescript theme={null}
const agent = await client.agents.create({
  name: 'My Agent',
  slug: 'my-agent',  // optional
  gitRepoUrl: 'https://github.com/user/my-agent',
});
```

***

### delete(slug)

Delete an agent.

```typescript theme={null}
await client.agents.delete(slug);
```

**Parameters:**

| Name   | Type     | Description      |
| ------ | -------- | ---------------- |
| `slug` | `string` | The agent's slug |

**Returns:** `Promise<void>`

**Example:**

```typescript theme={null}
await client.agents.delete('my-agent');
```

<Warning>
  This permanently deletes the agent, its secrets, and all invocation history.
</Warning>

***

### deploy(slug)

Deploy an agent.

```typescript theme={null}
const agent = await client.agents.deploy(slug);
```

**Parameters:**

| Name   | Type     | Description      |
| ------ | -------- | ---------------- |
| `slug` | `string` | The agent's slug |

**Returns:** `Promise<Agent>`

**Example:**

```typescript theme={null}
const agent = await client.agents.deploy('my-agent');
console.log(agent.status); // 'deploying' → 'active'
```

<Note>
  Deployment is asynchronous. The returned agent will have status `deploying`. Poll `get()` to check when it becomes `active`.
</Note>

***

### stop(slug)

Stop a running agent.

```typescript theme={null}
const agent = await client.agents.stop(slug);
```

**Parameters:**

| Name   | Type     | Description      |
| ------ | -------- | ---------------- |
| `slug` | `string` | The agent's slug |

**Returns:** `Promise<Agent>`

**Example:**

```typescript theme={null}
const agent = await client.agents.stop('my-agent');
console.log(agent.status); // 'stopped'
```

***

### invoke(slug, options)

Invoke an agent with a prompt.

```typescript theme={null}
const result = await client.agents.invoke(slug, options);
```

**Parameters:**

| Name                | Type     | Required | Description                            |
| ------------------- | -------- | -------- | -------------------------------------- |
| `slug`              | `string` | Yes      | The agent's slug                       |
| `options.prompt`    | `string` | Yes      | The prompt to send                     |
| `options.sessionId` | `string` | No       | Session ID for conversation continuity |

**Returns:** `Promise<InvocationResponse>`

**Example:**

```typescript theme={null}
const result = await client.agents.invoke('my-agent', {
  prompt: 'What files are in the current directory?'
});

console.log(result.response_content);
console.log(`Cost: $${result.total_cost_usd}`);
console.log(`Duration: ${result.duration_ms}ms`);
```

**With session (multi-turn conversation):**

```typescript theme={null}
// First turn
const result1 = await client.agents.invoke('my-agent', {
  prompt: 'Create a file called hello.txt',
  sessionId: 'my-session',
});

// Second turn (same session, sandbox preserved)
const result2 = await client.agents.invoke('my-agent', {
  prompt: 'What did you just create?',
  sessionId: 'my-session',
});
```

**Response:**

```typescript theme={null}
{
  invocation_id: 'inv_abc123',
  session_id: 'my-session',
  response_content: 'The current directory contains...',
  input_tokens: 124,
  output_tokens: 1110,
  total_cost_usd: 0.02,
  duration_ms: 2341,
  status: 'completed'
}
```

***

### uploadCode(slug, file, filename, options?)

Upload code directly to an agent and deploy.

```typescript theme={null}
const result = await client.agents.uploadCode(slug, file, filename, options?);
```

**Parameters:**

| Name                 | Type      | Required | Description                                |
| -------------------- | --------- | -------- | ------------------------------------------ |
| `slug`               | `string`  | Yes      | The agent's slug                           |
| `file`               | `Blob`    | Yes      | The code archive file                      |
| `filename`           | `string`  | Yes      | Filename (e.g., `'code.tar.gz'`)           |
| `options.autoDeploy` | `boolean` | No       | Auto-deploy after upload (default: `true`) |

**Returns:** `Promise<UploadResponse>`

**Example:**

```typescript theme={null}
const file = new Blob([tarGzBuffer], { type: 'application/gzip' });
const result = await client.agents.uploadCode('my-agent', file, 'code.tar.gz');
console.log(result.status); // 'active'
```

***

### listSecrets(slug)

List secret keys for an agent (values are never returned).

```typescript theme={null}
const secrets = await client.agents.listSecrets(slug);
```

**Parameters:**

| Name   | Type     | Description      |
| ------ | -------- | ---------------- |
| `slug` | `string` | The agent's slug |

**Returns:** `Promise<Secret[]>`

**Example:**

```typescript theme={null}
const secrets = await client.agents.listSecrets('my-agent');
// [{ key: 'OPENAI_API_KEY' }, { key: 'DATABASE_URL' }]
```

***

### setSecret(slug, key, value)

Set a secret for an agent.

```typescript theme={null}
await client.agents.setSecret(slug, key, value);
```

**Parameters:**

| Name    | Type     | Description      |
| ------- | -------- | ---------------- |
| `slug`  | `string` | The agent's slug |
| `key`   | `string` | The secret key   |
| `value` | `string` | The secret value |

**Returns:** `Promise<void>`

**Example:**

```typescript theme={null}
await client.agents.setSecret('my-agent', 'OPENAI_API_KEY', 'sk-xxx');
```

***

### deleteSecret(slug, key)

Delete a secret from an agent.

```typescript theme={null}
await client.agents.deleteSecret(slug, key);
```

**Parameters:**

| Name   | Type     | Description              |
| ------ | -------- | ------------------------ |
| `slug` | `string` | The agent's slug         |
| `key`  | `string` | The secret key to delete |

**Returns:** `Promise<void>`

**Example:**

```typescript theme={null}
await client.agents.deleteSecret('my-agent', 'OLD_API_KEY');
```

***

## Full Example

```typescript theme={null}
import { CastariClient } from '@castari/sdk';

async function main() {
  const client = new CastariClient({
    apiKey: process.env.CASTARI_API_KEY,
  });

  // List all agents
  const agents = await client.agents.list();
  console.log(`You have ${agents.length} agents`);

  // Get specific agent
  const agent = await client.agents.get('my-agent');

  if (agent.status !== 'active') {
    // Deploy if not active
    await client.agents.deploy('my-agent');
  }

  // Invoke
  const result = await client.agents.invoke('my-agent', {
    prompt: 'Write a haiku about coding',
  });

  console.log(result.response_content);
}

main();
```

## See Also

* [Secrets API](/sdk/secrets) — Manage secrets
* [Types](/sdk/types) — TypeScript interfaces
* [cast invoke](/cli/invoke) — CLI equivalent