Agents API

The Agents API lets you list, create, deploy, and invoke agents. Access via client.agents:

const client = new CastariClient({ apiKey: '...' });
const agents = client.agents;

Methods

list()

List all agents for the authenticated user.

const agents = await client.agents.list();

Returns: Promise<Agent[]> Example:

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.

const agent = await client.agents.get(slug);

Parameters:

Name	Type	Description
`slug`	`string`	The agent’s unique slug

Returns: Promise<Agent> Example:

const agent = await client.agents.get('my-agent');
console.log(agent.status); // 'active'

Errors:

404 — Agent not found

create(options)

Create a new agent.

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:

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.

await client.agents.delete(slug);

Parameters:

Name	Type	Description
`slug`	`string`	The agent’s slug

Returns: Promise<void> Example:

await client.agents.delete('my-agent');

This permanently deletes the agent, its secrets, and all invocation history.

deploy(slug)

Deploy an agent.

const agent = await client.agents.deploy(slug);

Parameters:

Name	Type	Description
`slug`	`string`	The agent’s slug

Returns: Promise<Agent> Example:

const agent = await client.agents.deploy('my-agent');
console.log(agent.status); // 'deploying' → 'active'

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

stop(slug)

Stop a running agent.

const agent = await client.agents.stop(slug);

Parameters:

Name	Type	Description
`slug`	`string`	The agent’s slug

Returns: Promise<Agent> Example:

const agent = await client.agents.stop('my-agent');
console.log(agent.status); // 'stopped'

invoke(slug, options)

Invoke an agent with a prompt.

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:

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

// 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:

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

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:

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

const secrets = await client.agents.listSecrets(slug);

Parameters:

Name	Type	Description
`slug`	`string`	The agent’s slug

Returns: Promise<Secret[]> Example:

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.

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:

await client.agents.setSecret('my-agent', 'OPENAI_API_KEY', 'sk-xxx');

deleteSecret(slug, key)

Delete a secret from an agent.

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:

await client.agents.deleteSecret('my-agent', 'OLD_API_KEY');

Full Example

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

Getting Started

CLI Reference

SDK Reference

Concepts

Guides

Agents API

Agents API

Methods

list()

get(slug)

create(options)

delete(slug)

deploy(slug)

stop(slug)

invoke(slug, options)

uploadCode(slug, file, filename, options?)

listSecrets(slug)

setSecret(slug, key, value)

deleteSecret(slug, key)

Full Example

See Also

​Agents API

​Methods

​list()

​get(slug)

​create(options)

​delete(slug)

​deploy(slug)

​stop(slug)

​invoke(slug, options)

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

​listSecrets(slug)

​setSecret(slug, key, value)

​deleteSecret(slug, key)

​Full Example

​See Also

Agents API

Methods

list()

get(slug)

create(options)

delete(slug)

deploy(slug)

stop(slug)

invoke(slug, options)

uploadCode(slug, file, filename, options?)

listSecrets(slug)

setSecret(slug, key, value)

deleteSecret(slug, key)

Full Example

See Also