Quick Start

This guide walks you through building a complete AI agent with tools, guardrails, and streaming — in under 50 lines of code.

What We're Building

A research agent that can:

Search the web for information
Read and summarize URLs
Refuse to answer questions about harmful topics
Stream responses in real-time

Step 1: Define Tools

Tools are functions that the agent can call. Each tool has a name, description, parameter schema, and an execute function.

import { Tool } from 'assistme-agent-sdk'
import { z } from 'zod'

const webSearch = Tool.create({
  name: 'web_search',
  description: 'Search the web for current information',
  parameters: z.object({
    query: z.string().describe('The search query'),
  }),
  execute: async ({ query }) => {
    // Your search implementation
    const response = await fetch(`https://api.search.com/search?q=${encodeURIComponent(query)}`)
    return response.json()
  },
})

const readUrl = Tool.create({
  name: 'read_url',
  description: 'Read and extract the content of a web page',
  parameters: z.object({
    url: z.string().url().describe('The URL to read'),
  }),
  execute: async ({ url }) => {
    const response = await fetch(url)
    const html = await response.text()
    // Convert HTML to text (simplified)
    return html.replace(/<[^>]*>/g, '').substring(0, 5000)
  },
})

Step 2: Add Guardrails

Guardrails validate inputs and outputs. They run automatically on every agent interaction.

import { Guardrail } from 'assistme-agent-sdk'

const contentFilter = Guardrail.input({
  name: 'content_filter',
  validate: async (input) => {
    const blocked = ['harmful_topic_1', 'harmful_topic_2']
    const lower = input.toLowerCase()
    for (const topic of blocked) {
      if (lower.includes(topic)) {
        return {
          allow: false,
          reason: 'This topic is outside my scope.',
        }
      }
    }
    return { allow: true }
  },
})

const outputGuard = Guardrail.output({
  name: 'pii_filter',
  validate: async (output) => {
    // Check for accidental PII in output
    const hasSSN = /\b\d{3}-\d{2}-\d{4}\b/.test(output)
    if (hasSSN) {
      return {
        allow: false,
        reason: 'Output contains potential PII. Redacting.',
        modified: output.replace(/\b\d{3}-\d{2}-\d{4}\b/g, '[REDACTED]'),
      }
    }
    return { allow: true }
  },
})

Step 3: Create the Agent

import { Agent } from 'assistme-agent-sdk'
import { claude } from 'assistme-agent-sdk-provider-claude'

const researcher = new Agent({
  name: 'researcher',
  model: claude('claude-sonnet-4-6'),
  instructions: `You are a research assistant. When asked a question:
1. Search the web for relevant information
2. Read the most promising results
3. Synthesize a clear, well-sourced answer

Always cite your sources with URLs.`,
  tools: [webSearch, readUrl],
  guardrails: {
    input: [contentFilter],
    output: [outputGuard],
  },
})

Step 4: Run the Agent

Simple Run

import { Runner } from 'assistme-agent-sdk'

const result = await Runner.run(researcher, {
  messages: [{ role: 'user', content: 'What are the latest developments in fusion energy?' }],
})

console.log(result.output)
console.log(`Tokens used: ${result.usage.totalTokens}`)
console.log(`Tools called: ${result.toolCalls.length}`)

Streaming Run

const stream = Runner.stream(researcher, {
  messages: [{ role: 'user', content: 'What are the latest developments in fusion energy?' }],
})

for await (const event of stream) {
  switch (event.type) {
    case 'text_delta':
      process.stdout.write(event.delta)
      break
    case 'tool_call':
      console.log(`\n🔧 Calling ${event.name}(${JSON.stringify(event.args)})`)
      break
    case 'tool_result':
      console.log(`✅ ${event.name} returned`)
      break
    case 'guardrail_triggered':
      console.log(`🛡️ ${event.guardrail}: ${event.reason}`)
      break
  }
}

const result = await stream.finalResult()

Step 5: Switch Providers

The same agent works with any provider — just swap the model:

import { openai } from 'assistme-agent-sdk-provider-openai'
import { gemini } from 'assistme-agent-sdk-provider-gemini'

// Same agent, different model
const researcherGPT = new Agent({
  ...researcher.config,
  model: openai('gpt-4o'),
})

const researcherGemini = new Agent({
  ...researcher.config,
  model: gemini('gemini-2.5-pro'),
})

Full Example

import { Agent, Tool, Guardrail, Runner } from 'assistme-agent-sdk'
import { claude } from 'assistme-agent-sdk-provider-claude'
import { z } from 'zod'

const webSearch = Tool.create({
  name: 'web_search',
  description: 'Search the web for current information',
  parameters: z.object({ query: z.string() }),
  execute: async ({ query }) => {
    return { results: [`Result for: ${query}`] }
  },
})

const researcher = new Agent({
  name: 'researcher',
  model: claude('claude-sonnet-4-6'),
  instructions: 'You are a research assistant. Use web search to answer questions.',
  tools: [webSearch],
})

const result = await Runner.run(researcher, {
  messages: [{ role: 'user', content: 'What is quantum computing?' }],
})

console.log(result.output)

Next Steps

Agents — Agent configuration, lifecycle, and patterns
Tools — Advanced tool patterns, MCP integration
Guardrails — Input/output validation, content filtering
Streaming — Real-time streaming events and patterns

Quick Start

On this page