agents

Examples

Runnable examples demonstrating every feature of the Agentspan TypeScript SDK.

---

Examples vs. Production

Every example uses runtime.run() for convenience. In production, you should not.

Examples call runtime.run() so you can try them in a single command — no setup, no separate processes. But run() blocks the caller until the agent finishes, which is fine for demos but not how you deploy real agents.

Production: Deploy → Serve → Run

In production, the three concerns are separated:

┌──────────────────────────────────────────────────────────────┐
│  1. DEPLOY (once, during CI/CD)                              │
│     Registers the agent definition with the Agentspan server │
│                                                              │
│     await runtime.deploy(agent);                             │
│     // or CLI: agentspan deploy --package my-agents          │
├──────────────────────────────────────────────────────────────┤
│  2. SERVE (long-running worker process)                      │
│     Listens for tool-call tasks and executes them            │
│                                                              │
│     await runtime.serve(agent);                              │
│     // typically run as a daemon or container                │
├──────────────────────────────────────────────────────────────┤
│  3. RUN (on-demand, from anywhere)                           │
│     Triggers an agent execution                              │
│                                                              │
│     agentspan run <agent-name> "prompt"                      │
│     // or SDK: await runtime.run("agent_name", "prompt");    │
│     // or REST API                                           │
└──────────────────────────────────────────────────────────────┘

Every example includes the deploy/serve pattern as commented code at the bottom of its main() function — look for the // Production pattern: comment.

See 63-deploy.ts, 63b-serve.ts, and 63c-run-by-name.ts for a complete working example of this pattern.

---

Getting Started

1. Install dependencies

The core examples (numbered files in this directory) are repository examples. They resolve @io-orkes/conductor-javascript/agents straight to the repo's src/agents/ sources (via this directory's tsconfig.json paths), so they are meant to be run from this checkout of the SDK:

# from the repository root
npm install

Framework-specific examples require additional packages. Install only what you need:

1.1. Copy/paste into your own project

If you want to copy an example into a separate project after npm install, switch its imports to the published package:

npm install @io-orkes/conductor-javascript zod

import { Agent, AgentRuntime } from '@io-orkes/conductor-javascript/agents';

The files under examples/ are not copy/paste-ready as-is because they import the SDK source tree directly.

Google ADK examples (adk/)

cd adk && npm install

LangGraph examples (langgraph/)

cd langgraph && npm install

OpenAI Agents SDK examples (openai/)

cd openai && npm install

Requires OPENAI_API_KEY environment variable.

Vercel AI examples (vercel-ai/)

cd vercel-ai && npm install

2. Configure your environment

Export environment variables:

export AGENTSPAN_LLM_MODEL=openai/gpt-4o-mini
export AGENTSPAN_SERVER_URL=http://localhost:8080/api
# export AGENTSPAN_AUTH_KEY=<key>     # if authentication is enabled
# export AGENTSPAN_AUTH_SECRET=<secret>

2.1. Choose a model

The AGENTSPAN_LLM_MODEL variable uses the provider/model-name format. Examples:

Provider	Model string	API key env var
OpenAI	anthropic/claude-sonnet-4-6 (default)	OPENAI_API_KEY
Anthropic	anthropic/claude-sonnet-4-20250514	ANTHROPIC_API_KEY
Google Gemini	google_gemini/gemini-2.0-flash	GOOGLE_GEMINI_API_KEY
AWS Bedrock	aws_bedrock/...	AWS credentials
Azure OpenAI	azure_openai/...	Azure credentials

3. Run an example

# Core agent examples (run from the repository root)
npx tsx examples/agents/01-basic-agent.ts
npx tsx examples/agents/15-agent-discussion.ts

# Framework-specific examples (install their deps first, see 1.1)
cd examples/agents/adk && npx tsx 01-basic-agent.ts
cd examples/agents/langgraph && npx tsx 01-hello-world.ts
cd examples/agents/openai && npx tsx 01-basic-agent.ts

---

Basic Examples

#	Example	What it demonstrates
01	Basic Agent	Simplest possible agent — single LLM, no tools
02	Tools	Multiple tool() functions, approval-required tools

Tool Calling

#	Example	What it demonstrates
02a	Simple Tools	Two tools (weather, stocks) — LLM picks the right one
02b	Multi-Step Tools	Chained tool calls: lookup → fetch → calculate → answer
03	Structured Output	Zod outputType for typed, validated responses
04	HTTP & MCP Tools	Server-side tools via httpTool() and mcpTool() — no workers needed
04b	MCP Weather	Real-time weather via an MCP server
14	Existing Workers	Use existing worker task functions directly as agent tools
33	Single Turn Tool	Single-turn tool invocation with immediate response
33	External Workers	Reference workers in other services — no local code needed

Multi-Agent Orchestration

#	Example	Pattern
05	Handoffs	LLM-driven delegation to sub-agents
06	Sequential Pipeline	Agents run in order, output chains forward
07	Parallel Agents	All agents run concurrently, results aggregated
08	Router Agent	Router selects which sub-agent runs
13	Hierarchical Agents	3-level nested hierarchy: CEO → leads → specialists
15	Agent Discussion	Round-robin debate between agents, piped to a summarizer
16	Random Strategy	Random agent selected each turn (brainstorming)
17	Swarm Orchestration	Automatic transitions via handoff conditions
18	Manual Selection	Human picks which agent speaks each turn
20	Constrained Transitions	Restrict which agents can follow which
29	Agent Introductions	Agents introduce themselves before a group discussion
38	Tech Trends	Multi-agent research pipeline with live HTTP API tools

Human-in-the-Loop

#	Example	What it demonstrates
09	Human-in-the-Loop	Tool approval gate — approve or reject before execution
09b	HITL with Feedback	Custom feedback via respond() — editorial review
09c	HITL with Streaming	Real-time event stream with approval pauses
09d	Human Tool	Human-as-a-tool for interactive conversations
27	User Proxy Agent	Human stand-in agent for interactive conversations

Guardrails & Safety

#	Example	What it demonstrates
10	Guardrails	Output validation with guardrail functions
21	Regex Guardrails	Pattern-based blocking (emails, SSNs) and allow-listing
22	LLM Guardrails	AI-powered content safety evaluation via a judge LLM
31	Tool Guardrails	Pre-execution validation on tool inputs
32	Human Guardrail	Pause agent for human review when output fails
35	Standalone Guardrails	Use guardrails as plain callables — no agent needed
36	Simple Agent Guardrails	Mixed regex + custom guardrails on agents
37	Fix Guardrail	Auto-correct output instead of retrying

Execution Modes

#	Example	What it demonstrates
11	Streaming	Real-time event stream with runtime.stream()
12	Long-Running	Async polling with runtime.start()

Credentials

#	Example	What it demonstrates
08	Credentials	Server-side credential injection
16	Isolated Tool	Credentials scoped to a single tool
16b	Non-Isolated	Credentials shared across tools
16e	HTTP Tool	Credentials in HTTP tool headers
16f	MCP Tool	Credentials in MCP tool headers

Deployment

#	Example	What it demonstrates
63	Deploy	Register agent with the server
63b	Serve	Start a long-running worker
63c	Run by Name	Execute a pre-deployed agent
63d	Serve from Package	Serve agents from a package
63e	Run Monitoring	Monitor running executions

Framework Integrations

Directory	Framework	Examples
adk/	Google ADK	35 examples — agents, tools, streaming, planners, security
langgraph/	LangGraph	45 examples — state graphs, react agents, memory, RAG
openai/	OpenAI Agents SDK	10 examples — agents, tools, handoffs, guardrails
vercel-ai/	Vercel AI SDK	10 examples — agents, tools, streaming, HITL
quickstart/	Agentspan Quickstart	5 examples — minimal getting-started guides