Building Your First Agent in Astreus

December 1, 2025

Learn to build your first AI agent with Astreus. A quick-start guide covering agent creation, task execution, and essential API methods.

ListenReady
0:00
2:18

Building AI agents doesn't need to be complicated. With Astreus, you can create a working agent in just a few lines of code. This tutorial covers the fundamentals using the real Astreus API.

Quick Start

You can clone the complete example or start from scratch:

Bash
git clone https://github.com/astreus-ai/your-first-agent
cd your-first-agent
npm install

Or install just the package:

Bash
npm install @astreus-ai/astreus

Environment Setup

Create a .env file with your configuration:

Env
OPENAI_API_KEY=sk-your-openai-api-key-here
DB_URL=sqlite://./astreus.db

The database URL can point to SQLite for local development or PostgreSQL for production.

Creating Your First Agent

Here's the basic agent implementation:

TypeScript
import { Agent } from '@astreus-ai/astreus';

const agent = await Agent.create({
  name: 'MyFirstAgent',
  model: 'gpt-4o',
  systemPrompt: 'You are a helpful assistant.'
});

The Agent.create() method takes three core parameters: a name for identification, the LLM model to use, and a system prompt that defines the agent's behavior and personality.

Working with Tasks

Tasks provide structure for agent interactions. Create a task with a prompt, then execute it:

TypeScript
const task = await agent.createTask({
  prompt: "Hello, introduce yourself"
});

const result = await agent.executeTask(task.id);
console.log(result.response);

The createTask() method generates a task object with an ID and status. The executeTask() method processes the task and returns the agent's response.

Running Your Agent

If you cloned the repository:

Bash
npm run dev

For a standalone script:

Bash
npx tsx index.ts

Core API Methods

Astreus provides three essential methods for basic agent operations:

  • Agent.create() - Creates a new agent instance with configuration
  • agent.createTask() - Generates a task with a prompt and optional metadata
  • agent.executeTask() - Executes a task by ID and returns the response

These methods form the foundation for building more complex agent systems.

Complete Example

Here's everything together:

TypeScript
import { Agent } from '@astreus-ai/astreus';

const agent = await Agent.create({
  name: 'MyFirstAgent',
  model: 'gpt-4o',
  systemPrompt: 'You are a helpful assistant.'
});

const task = await agent.createTask({
  prompt: "Hello, introduce yourself"
});

const result = await agent.executeTask(task.id);
console.log(result.response);

This creates an agent, assigns it a task, and logs the response. The agent uses GPT-4 to process the prompt and generate an answer.

What's Next

This is just the beginning. The Astreus framework supports more advanced features like memory, knowledge bases, vision capabilities, and multi-agent systems. Start with this foundation and expand as your needs grow.

Source Code

The complete working example is available on GitHub: astreus-ai/your-first-agent

This experiment is written for Astreus v0.5.37. Please ensure you are using a compatible version.

end