Skip to main content

​
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:
NameTypeDescription
slugstringThe 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:
NameTypeRequiredDescription
options.namestringYesDisplay name for the agent
options.slugstringNoUnique identifier (auto-generated from name if not provided)
options.descriptionstringNoAgent description
options.sourceType'git' | 'local'NoSource type (default: 'git')
options.gitRepoUrlstringNoGit 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:
NameTypeDescription
slugstringThe 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:
NameTypeDescription
slugstringThe 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:
NameTypeDescription
slugstringThe 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:
NameTypeRequiredDescription
slugstringYesThe agent’s slug
options.promptstringYesThe prompt to send
options.sessionIdstringNoSession 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:
NameTypeRequiredDescription
slugstringYesThe agent’s slug
fileBlobYesThe code archive file
filenamestringYesFilename (e.g., 'code.tar.gz')
options.autoDeploybooleanNoAuto-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:
NameTypeDescription
slugstringThe 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:
NameTypeDescription
slugstringThe agent’s slug
keystringThe secret key
valuestringThe 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:
NameTypeDescription
slugstringThe agent’s slug
keystringThe 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();

​
See Also