Celeris Docs

Agents

Understanding AI agents in Celeris.

Agents are the core building blocks of Celeris. They are AI-powered entities that can understand instructions, process information, and take actions.

What is an Agent?

An agent is a configured AI model with specific instructions, capabilities, and constraints. Think of agents as specialized workers that can:

  • Understand natural language inputs
  • Make decisions based on context
  • Execute actions and return results
  • Learn from feedback

Agent Anatomy

Every agent has these components:

const agent = {
  // Identity
  id: 'agt_xxxx',
  name: 'Customer Support Agent',


  // Behavior
  instructions: 'You are a helpful customer support agent...',
  model: 'gpt-4',


  // Capabilities
  tools: ['search_knowledge_base', 'create_ticket'],


  // Constraints
  guardrails: {
    maxTokens: 1000,
    temperature: 0.7,
  },
};

Creating Agents

Basic Agent

const agent = await celeris.agents.create({
  name: 'Simple Assistant',
  instructions: 'You are a helpful assistant.',
  model: 'gpt-4',
});

Agent with Tools

Tools give agents the ability to take actions:

const agent = await celeris.agents.create({
  name: 'Research Agent',
  instructions: 'You are a research assistant...',
  model: 'gpt-4',
  tools: [
    {
      name: 'web_search',
      description: 'Search the web for information',
      parameters: {
        query: { type: 'string', required: true },
      },
    },
  ],
});

Agent with Memory

Enable memory for context retention across conversations:

const agent = await celeris.agents.create({
  name: 'Personal Assistant',
  instructions: 'Remember user preferences...',
  model: 'gpt-4',
  memory: {
    enabled: true,
    type: 'conversation',
    retention: '30d',
  },
});

Agent Types

Chat Agents

Conversational agents for customer support, Q&A, and interactive experiences.

Task Agents

Single-purpose agents for specific tasks like data processing or classification.

Autonomous Agents

Self-directed agents that can plan and execute multi-step tasks.

Running Agents

Synchronous Execution

Wait for the result:

const response = await celeris.agents.run(agent.id, {
  input: 'What is the weather today?',
});


console.log(response.output);

Asynchronous Execution

For long-running tasks:

const execution = await celeris.agents.runAsync(agent.id, {
  input: 'Analyze this dataset...',
  webhookUrl: 'https://yourapp.com/webhooks',
});


console.log('Execution ID:', execution.id);
// Result delivered via webhook

Streaming

Stream responses in real-time:

const stream = await celeris.agents.stream(agent.id, {
  input: 'Write a long story...',
});


for await (const chunk of stream) {
  process.stdout.write(chunk.text);
}

Agent Lifecycle

Created → Active → Paused → Archived → Deleted
           ↑__________|
StateDescription
createdAgent exists but not activated
activeAgent can receive executions
pausedTemporarily disabled
archivedPreserved but inactive
deletedPermanently removed

Best Practices

Clear Instructions

Write detailed, specific instructions. Vague instructions lead to unpredictable behavior.

Do’s

  • Use specific, actionable instructions
  • Define clear boundaries and constraints
  • Test with diverse inputs
  • Monitor execution metrics
  • Version your agent configurations

Don’ts

  • Don’t include sensitive data in instructions
  • Don’t use agents for security-critical decisions
  • Don’t skip testing before production
  • Don’t ignore guardrails