Skip to main content

​
Your first agent

Build a working AI agent in just a few lines of code.
1

Install the package

npm install @deepagents/agent zod
You’ll also need an AI SDK provider:
npm install @ai-sdk/openai
2

Set your API key

Configure your OpenAI API key:
export OPENAI_API_KEY="your-api-key"
3

Create your first agent

Create a simple assistant agent:
import { openai } from '@ai-sdk/openai';
import { agent, execute } from '@deepagents/agent';

const assistant = agent({
  name: 'assistant',
  model: openai('gpt-4o'),
  prompt: 'You are a helpful assistant.',
});

const stream = execute(assistant, 'Hello! What can you help me with?', {});

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

​
Add tools to your agent

Agents become powerful when they can use tools. Here’s how to add a weather tool: 
import { openai } from '@ai-sdk/openai';
import { tool } from 'ai';
import { z } from 'zod';
import { agent, execute } from '@deepagents/agent';

const weatherTool = tool({
  description: 'Get weather for a location',
  parameters: z.object({
    location: z.string(),
  }),
  execute: async ({ location }) => {
    // In production, call a real weather API
    return { temperature: 72, condition: 'sunny', location };
  },
});

const weatherAgent = agent({
  name: 'weather_agent',
  model: openai('gpt-4o'),
  prompt: 'You help users check the weather.',
  tools: { weather: weatherTool },
});

const stream = execute(weatherAgent, 'What is the weather in Tokyo?', {});
console.log(await stream.text);
The agent will automatically:
  1. Recognize it needs weather data
  2. Call the weather tool with the location
  3. Use the tool’s response to answer the question

​
Create a multi-agent system

Build agents that delegate to specialized agents: 
import { openai } from '@ai-sdk/openai';
import { agent, instructions, swarm } from '@deepagents/agent';

// Research specialist
const researcher = agent({
  name: 'researcher',
  model: openai('gpt-4o'),
  prompt: 'You research topics and provide detailed information.',
  handoffDescription: 'Handles research and fact-finding tasks',
});

// Writing specialist
const writer = agent({
  name: 'writer',
  model: openai('gpt-4o'),
  prompt: 'You write clear, engaging content based on research.',
  handoffDescription: 'Handles writing and content creation',
});

// Coordinator
const coordinator = agent({
  name: 'coordinator',
  model: openai('gpt-4o'),
  prompt: instructions({
    purpose: ['Coordinate research and writing tasks'],
    routine: [
      'Analyze the request',
      'Use transfer_to_researcher for fact-finding',
      'Use transfer_to_writer for content creation',
    ],
  }),
  handoffs: [researcher, writer],
});

// The coordinator automatically delegates to specialists
const stream = swarm(coordinator, 'Write a blog post about AI agents', {});
Agents automatically get transfer_to_<agent_name> tools and coordinate seamlessly.

​
Get structured output

Extract type-safe data from AI responses: 
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';
import { agent, generate } from '@deepagents/agent';

const analyzer = agent({
  name: 'analyzer',
  model: openai('gpt-4o'),
  prompt: 'Analyze the sentiment of the given text.',
  output: z.object({
    sentiment: z.enum(['positive', 'negative', 'neutral']),
    confidence: z.number(),
    keywords: z.array(z.string()),
  }),
});

const result = await generate(analyzer, 'I love this product!', {});
console.log(result.output);
// { sentiment: 'positive', confidence: 0.95, keywords: ['love', 'product'] }

​
Query databases with natural language

Use Text2SQL for natural language database queries: 
import { Sqlite } from '@deepagents/text2sql/sqlite';
import { openai } from '@ai-sdk/openai';

const text2sql = new Sqlite(
  './database.db',
  openai('gpt-4o')
);

const result = await text2sql.query(
  'What are the top 5 customers by revenue?'
);

console.log(result.rows);
Text2SQL automatically introspects your schema, validates queries, and handles multi-turn conversations.

​
Add RAG capabilities

Ingest documents and perform semantic search: 
import { ingest, similaritySearch } from '@deepagents/retrieval';
import { GithubConnector } from '@deepagents/retrieval/connectors';

// Ingest documentation
await ingest({
  connector: new GithubConnector({
    owner: 'yourorg',
    repo: 'yourrepo',
    path: 'docs',
  }),
  store: './embeddings.db',
});

// Search
const results = await similaritySearch({
  query: 'How do I configure authentication?',
  store: './embeddings.db',
  topK: 5,
});

console.log(results);

​
Evaluate your agents

Test and score agent performance: 
import { evaluate, dataset, exactMatch } from '@deepagents/evals';

const summary = await evaluate({
  name: 'agent-eval',
  model: 'gpt-4o',
  dataset: dataset([
    { input: 'What is 2+2?', expected: '4' },
    { input: 'What is 3+3?', expected: '6' },
  ]),
  task: async (item) => {
    const response = await callYourAgent(item.input);
    return { output: response };
  },
  scorers: { exact: exactMatch },
});

console.log(summary);

​
Next steps

Core concepts

Learn about agents, tools, and handoffs

Agent framework

Deep dive into the agent framework

Text2SQL

Natural language to SQL

RAG & retrieval

Document ingestion and semantic search

Build docs developers (and LLMs) love

Get started for freeTalk to us