Skip to content

first-agent.md

Latest commit

 

History

History
90 lines (68 loc) · 3.36 KB

first-agent.md

File metadata and controls

90 lines (68 loc) · 3.36 KB

Your First Agent

This walkthrough assumes you have installed @gemstack/ai-sdk and registered a provider.

A one-line prompt

import { agent } from '@gemstack/ai-sdk'

const response = await agent('You are a helpful assistant.')
  .prompt('Summarize the transformer architecture in one sentence.')

console.log(response.text)

agent(instructions) returns an agent; .prompt(input) runs it and resolves to an AgentResponse with .text, .steps, .usage, and more.

Three agent shapes

Pick whichever reads best at the call site:

import { agent, AI, Agent, stepCountIs } from '@gemstack/ai-sdk'

// Inline, one-off
const r1 = await agent('You summarize text.').prompt('Summarize this...')

// Facade with the default model
const r2 = await AI.prompt('Hello world')

// Configured anonymous agent - tools + options together
const r3 = await agent({
  instructions: 'You help find users.',
  model: 'anthropic/claude-sonnet-4-6',
  tools: [searchTool],
}).prompt('Find all admins')

// Reusable typed class
class SearchAgent extends Agent {
  instructions() { return 'You help find users.' }
  model()        { return 'anthropic/claude-sonnet-4-6' }
  tools()        { return [searchTool] }
  stopWhen()     { return stepCountIs(5) }
}
const r4 = await new SearchAgent().prompt('Find all admins')

A class is the right shape once an agent has tools, a fixed model, middleware, or memory - everything lives in one place and the type is reusable.

Giving the agent a tool

Tools let the agent call your code. Define one with toolDefinition(...), declare its input with Zod, and attach a .server() handler:

import { agent, toolDefinition } from '@gemstack/ai-sdk'
import { z } from 'zod'

const searchTool = toolDefinition({
  name:        'search_users',
  description: 'Search users by name or email',
  inputSchema: z.object({
    query: z.string().describe('Name or email substring'),
    limit: z.number().int().min(1).max(50).default(10),
  }),
}).server(async ({ query, limit }) => {
  return await db.users.search(query, limit)
})

const response = await agent({
  instructions: 'You help find users.',
  tools: [searchTool],
}).prompt('Find all admins')

The agent decides when to call the tool, validates the arguments against inputSchema before your handler runs, and feeds the result back to the model. Inspect response.steps for the full trace.

Where to go next

You want to… Read
Compose tools, skills, and a multi-agent supervisor into one app Build a Multi-Agent App
Understand the agent loop, sub-agents, multi-step runs Agents
Go deeper on tools, scoped tools, client tools, approval gates Tools
Add more model providers Providers
Stream tokens and tool progress to a UI Streaming
Get typed objects back instead of text Structured Output
Persist conversations and give the agent memory Memory & Persistence
Retrieval-augmented generation over your documents Vector Stores & RAG
Test agents without hitting a real model Testing & Evals
See the whole family and how the pieces fit Packages overview