agents

Examples

Runnable examples demonstrating every feature of the Agentspan TypeScript SDK.

200+ runnable examples in total: the core examples cataloged below, plus the quickstart/ guides and framework ports for Google ADK, LangGraph, OpenAI Agents SDK, and Vercel AI 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 Conductor 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 CONDUCTOR_AGENT_LLM_MODEL=openai/gpt-4o-mini
export CONDUCTOR_SERVER_URL=http://localhost:8080/api
# export CONDUCTOR_AUTH_KEY=<key>     # if authentication is enabled
# export CONDUCTOR_AUTH_SECRET=<secret>

2.1. Choose a model

The CONDUCTOR_AGENT_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
—	Kitchen Sink	Content publishing platform — every major feature in one example

Tool Calling & Structured Output

#	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
09	Structured Output (agent run)	Zod schema as outputType — typed result from a full agent run
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
45	Agent Tool	Invoke a child agent inline as a function call (vs handoff)
51	Shared State	Tools sharing state across calls via ToolContext
71	API Tool	Auto-discover endpoints from OpenAPI, Swagger, or Postman specs
74	CLI Error Output	Agent sees stdout/stderr when a CLI tool exits non-zero

Multi-Agent Orchestration

#	Example	Pattern
03	Multi-Agent	Three strategies in one file: sequential, parallel, handoff
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
19	Composable Termination	AND/OR rules for stopping multi-agent runs
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
41	Sequential Pipeline with Tools	Stage-level tools in a pipeline
46	Transfer Control	Constrained handoff paths between sub-agents
52	Nested Strategies	Parallel agents inside a sequential pipeline
58	Scatter-Gather	Massive parallel multi-agent orchestration
64	Swarm with Tools	Sub-agents with their own domain tools
65	Parallel with Tools	Each parallel branch has its own tools
66	Handoff to Parallel	Delegate to a multi-agent group
67	Router to Sequential	Route to a pipeline sub-agent

Human-in-the-Loop

#	Example	What it demonstrates
06	HITL Basics	Approval-required tool with interactive console prompts
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

Guardrails & Safety

#	Example	What it demonstrates
04	Guardrail Types	Regex, LLM, and custom guardrails in one file
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
42	Security Testing	Multi-agent security testing pipeline
43	Data Security Pipeline	Data-safety pipeline with guardrails
44	Safety Guardrails	Safety guardrails pipeline
62	CLI Tool Guardrails	Safe command execution
90	Guardrail E2E Tests	Full 3×3×3 matrix: position × type × onFail (27 tests)

Streaming & Execution Modes

#	Example	What it demonstrates
05	Streaming Basics	runtime.stream() with for-await-of and event type switching
11	Streaming	Real-time event stream with runtime.stream()
12	Long-Running	Async polling with runtime.start()

Memory & Context

#	Example	What it demonstrates
07	Memory	ConversationMemory windowing + SemanticMemory similarity search
25	Semantic Memory	Long-term memory with similarity-based retrieval
49	Include Contents	Control conversation context passed to sub-agents
68	Context Condensation	Stress test: server condenses long history automatically

Planning

#	Example	What it demonstrates
48	Planner	Agent that plans before executing
57	Plan (Dry Run)	Compile an agent without executing it
108	Plan-Execute Refs	Pipe whole step outputs downstream with new Ref("step_id")
115	Plan-Execute Planner Context	Inject domain-specific planning rules via plannerContext

Code Execution

#	Example	What it demonstrates
10	Code Execution	LocalCodeExecutor.asTool() attached to an agent
24	Code Executors	Executor types: local subprocess vs Docker sandbox
39	Local Code Execution	Three config styles, incl. language/command restrictions
39a	Docker Code Execution	Docker-sandboxed execution
39b	Jupyter Code Execution	Jupyter kernel execution
39c	Serverless Code Execution	Serverless sandbox execution

Skills

#	Example	What it demonstrates
30	Skills: /dg Review	Load the /dg skill as a durable agent
31	Skills: Conductor	Load the conductor skill for workflow management
32	Skills: Multi-Agent	Skills as sub-agents in multi-agent workflows

Observability & Callbacks

#	Example	What it demonstrates
23	Token & Cost Tracking	Monitor LLM token usage per agent run
26	OpenTelemetry Tracing	Industry-standard observability
47	Callbacks	CallbackHandler hooks around LLM and tool calls
53	Agent Lifecycle Callbacks	Composable handler classes, chained per position

Model & Provider Features

#	Example	What it demonstrates
28	GPT Assistant Agent	Wrap the OpenAI Assistants API as a Conductor agent
30	Multimodal Agent	Analyze images and video with vision-capable models
40	Media Generation Agent	Generate media assets from an agent
50	Thinking Config	Enable extended reasoning for complex tasks

Credentials

#	Example	What it demonstrates
08	Credentials	Server-side credential injection
16	Isolated Tool	Per-user secrets injected into isolated tool subprocesses
16b	Non-Isolated	In-process tools using getCredential()
16c	CLI Tools	CLI tools with explicit credential declarations
16d	GitHub CLI	gh with automatic credential injection
16e	HTTP Tool	Server-side credential resolution in HTTP tool headers
16f	MCP Tool	Server-side credential resolution in MCP tool headers
16g	Framework Passthrough	Credential injection into framework-wrapped agents
16h	External Worker	External worker credential resolution
16i	LangChain	LangChain AgentExecutor with credential injection
16j	OpenAI SDK	OpenAI Agents SDK with credential injection
16k	Google ADK	Google ADK agent with credential injection

Deployment & Scheduling

#	Example	What it demonstrates
17	Scheduled Agent	Deploy an agent on a cron schedule
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

End-to-End Use Cases

#	Example	What it demonstrates
54	Software Bug Assistant	agentTool + mcpTool for bug triage
55	ML Engineering	Multi-agent ML pipeline
56	RAG Agent	Vector search + document indexing
59	Coding Agent	Write, review, and fix code with a QA tester
60	GitHub Coding Agent	Pick an issue, code the fix, create a PR
60a	GitHub Coding Agent (Simple)	Simplified single-agent variant
61	GitHub Coding Agent (Chained)	Issue-to-PR pipeline
70	CE Support Agent	Investigate a support ticket across Zendesk, JIRA, HubSpot, Notion, and GitHub

Framework Integrations

Directory	Framework	Examples
adk/	Google ADK	Agents, tools, streaming, planners, security
langgraph/	LangGraph	State graphs, react agents, memory, RAG
openai/	OpenAI Agents SDK	Agents, tools, handoffs, guardrails
vercel-ai/	Vercel AI SDK	Agents, tools, streaming, HITL
quickstart/	Agentspan Quickstart	Minimal getting-started guides