agentry

Agentry 🤖 🏗️

Compose and reuse your AI agents like React components.

What is Agentry?

Agentry adapts React’s component model for AI agents. Define behavior declaratively, compose agents like you would components, and let the framework manage the flow and execution.

[!WARNING] This library is in active development.

[!NOTE] Supports OpenAI and Anthropic models.

Quick Start

Installation

bun add agentry react zod

# for anthropic
bun add @anthropic-ai/sdk
export ANTHROPIC_API_KEY="sk-ant-***"

# for openai
bun add openai
export OPENAI_API_KEY="sk-***"

Next, in your tsconfig.json:

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "react",
    "module": "ESNext",
    "target": "ESNext",
    "moduleResolution": "bundler"
  }
}

Creating an Agent

In agent.tsx:

import Anthropic from '@anthropic-ai/sdk'
import { run, Agent, System, Tools, Tool, Message } from 'agentry'
import { z } from 'zod'

const result = await run(
  <Agent provider="anthropic" model="claude-haiku-4-5" maxTokens={1024}>
    <System>You are a helpful math assistant</System>
    <Tools>
      <Tool
        name="calculator"
        description="Perform calculations"
        parameters={z.object({
          operation: z.enum(['add', 'subtract', 'multiply', 'divide']),
          a: z.number(),
          b: z.number(),
        })}
        handler={async ({ operation, a, b }) => {
          const ops = {
            add: a + b,
            subtract: a - b,
            multiply: a * b,
            divide: a / b,
          }
          return String(ops[operation])
        }}
      />
    </Tools>
    <Message role="user">What is 42 + 17?</Message>
  </Agent>,
  {
    providers: { anthropic: { client: new Anthropic() } },
  },
)

console.log(result.content)

Run it:

bun run agent.tsx

Features

• Dynamic tools via React state - Add/remove tools during execution with useState
• React hooks - useExecutionState(), useMessages() for reactive state
• Declarative subagents - Use <AgentTool> to create subagents with type-safe parameters
• Type-safe tools - Handler params inferred from Zod schemas
• Streaming support - Stream responses
• WebSocket mode (OpenAI) - Persistent connection via websocket prop reduces per-turn latency in multi-tool loops
• Programmatic agent spawning - Spawn and execute agents on-demand from tool handlers using context.runAgent()
• Cross-provider subagents - Mix providers across parent/subagent boundaries
• Compaction control - Automatic message compaction for long conversations to manage context window usage
• Conditional rendering - Use <Condition> to conditionally render agent components based on state or natural language intent
• Structured outputs - Use strict on tools
• Prompt caching - Supports Anthropic's prompt caching

Providers

Agentry supports multiple providers with a single declarative API.

• Root agentry exports the provider-agnostic core (run, Agent, hooks, custom tools).
• Provider modules export provider clients and built-ins:
  • agentry/anthropic
  • agentry/openai
• Built-ins are treated as regular tools in execution (no per-provider capability matrix to maintain).

Reusable instance

import Anthropic from '@anthropic-ai/sdk'
import { createAI, Agent, Message, Tools } from 'agentry'
import { WebSearch } from 'agentry/anthropic'

const ai = createAI({
  providers: { anthropic: { client: new Anthropic() } },
})

const result = await ai.run(
  <Agent provider="anthropic" model="claude-sonnet-4-5" maxTokens={1024}>
    <Tools>
      <WebSearch maxUses={3} />
    </Tools>
    <Message role="user">Find the latest React release notes</Message>
  </Agent>,
)

Examples

Want to see code? See examples/

Example	Description
demo.tsx	Company research with web search
basic.tsx	Simple calculator tool
interactive.tsx	Multi-turn conversations with streaming
subagents.tsx	Manager delegating to specialists
hooks.tsx	Hooks, composition, and dynamic tools
web-search.tsx	Web search workflows
mcp.tsx	MCP server integration
chatbot.tsx	Terminal-based chatbot
create-subagent.tsx	Dynamic subagent creation
anthropic/cache-ephemeral.tsx	Prompt caching with ephemeral content
conditions.tsx	State-based and NL condition rendering
anthropic/thinking.tsx	Extended thinking with interleaved support
workflow.tsx	Interactive authentication workflow
conversation-persistence.tsx	Conversation save/load
openai/basic.tsx	OpenAI Responses API basic usage
cross-provider/subagents.tsx	OpenAI parent + Anthropic subagents
openai/codex-subagent.tsx	OpenAI Codex subagent
openai/built-ins.tsx	OpenAI built-ins: WebSearch, CodeExecution, and MCP
openai/websocket.tsx	OpenAI WebSocket mode for lower-latency multi-tool loops
compaction.tsx	Context compaction demo (works with Anthropic and OpenAI)

Run an example:

echo "ANTHROPIC_API_KEY=sk-ant-***" > .env
# echo "OPENAI_API_KEY=sk-***" >> .env
bun run example:basic
# OpenAI examples:
bun run example:openai:basic
# provider-agnostic examples (set EXAMPLE_PROVIDER=openai if needed):
bun run example:chatbot
# Anthropic-specific examples:
bun run example:anthropic:thinking

Core Concepts

Batch vs Interactive Mode

Batch mode (default) - Runs to completion:

const result = await run(<Agent provider="anthropic">...</Agent>, {
  providers: { anthropic: { client: new Anthropic() } },
})

Interactive mode - Returns a handle for ongoing interaction:

const agent = await run(<Agent provider="anthropic">...</Agent>, {
  mode: 'interactive',
  providers: { anthropic: { client: new Anthropic() } },
})
await agent.sendMessage('Hello')
for await (const event of agent.stream('Tell me more')) {
  if (event.type === 'text') process.stdout.write(event.text)
}
agent.close()

Subagents

Create subagents using <AgentTool> with type-safe parameters:

<Agent name="manager" provider="anthropic" model="claude-haiku-4-5">
  <Tools>
    <AgentTool
      name="researcher"
      description="Research specialist"
      parameters={z.object({
        topic: z.string().describe('The topic to research'),
      })}
      agent={(input) => (
        <Agent name="researcher">
          <System>You are a research expert.</System>
          <Message role="user">Research: {input.topic}</Message>
        </Agent>
      )}
    />
  </Tools>
</Agent>

The manager can call researcher(topic="...") and the framework spawns and runs the subagent with the provided parameters.

Programmatic Agent Spawning

Spawn agents programmatically from within tool handlers using context.runAgent(). This allows for conditional agent creation, parallel execution, and dynamic agent selection based on runtime data:

<Agent provider="anthropic" model="claude-haiku-4-5">
  <Tools>
    <Tool
      name="analyze_code"
      description="Analyze code by spawning a specialist agent"
      parameters={z.object({
        code: z.string(),
        language: z.enum(['python', 'typescript', 'rust']),
      })}
      handler={async (input, context) => {
        // Spawn different agents based on language
        const result = await context.runAgent(
          input.language === 'python' ? (
            <Agent name="python-expert">
              <System>You are a Python expert</System>
              <Message role="user">Analyze: {input.code}</Message>
            </Agent>
          ) : (
            <Agent name="typescript-expert">
              <System>You are a TypeScript expert</System>
              <Message role="user">Analyze: {input.code}</Message>
            </Agent>
          ),
        )
        return result.content
      }}
    />
  </Tools>
</Agent>

You can also spawn multiple agents in parallel:

handler={async (input, context) => {
  const [techResult, bizResult] = await Promise.all([
    context.runAgent(<TechnicalAnalyst content={input.content} />),
    context.runAgent(<BusinessAnalyst content={input.content} />),
  ])
  return `Tech: ${techResult.content}\nBiz: ${bizResult.content}`
}}

Cross-provider subagents

<AgentTool> and context.runAgent(...) can run subagents on a different provider than the parent:

import Anthropic from '@anthropic-ai/sdk'
import OpenAI from 'openai'
import { createAI, Agent, AgentTool, Message, Tools } from 'agentry'
import { z } from 'zod'

const ai = createAI({
  providers: {
    openai: { client: new OpenAI() },
    anthropic: { client: new Anthropic() },
  },
})

await ai.run(
  <Agent provider="openai" model="gpt-5-mini">
    <Tools>
      <AgentTool
        name="claude_researcher"
        description="Research with Anthropic"
        parameters={z.object({ topic: z.string() })}
        agent={({ topic }) => (
          <Agent provider="anthropic" model="claude-sonnet-4-5">
            <Message role="user">Research: {topic}</Message>
          </Agent>
        )}
      />
    </Tools>
    <Message role="user">Use claude_researcher for React 19 updates.</Message>
  </Agent>,
)

State-Driven Tools

Tools can be added/removed during execution using React state:

function DynamicAgent() {
  const [hasAdvanced, setHasAdvanced] = useState(false)
  return (
    <Agent provider="anthropic" model="claude-haiku-4-5">
      <System>
        You are a helpful assistant that can analyze technical and business content.
        You can unlock advanced analysis tools by calling the unlock_advanced tool.
      </System>
      <Tools>
        <Tool
          name="unlock_advanced"
          parameters={z.object({})}
          handler={async () => {
            setHasAdvanced(true) // Adds new tool on next render
            return 'Unlocked!'
          }}
        />
        {hasAdvanced && <Tool name="advanced_analysis" ... />}
      </Tools>
      <Message role="user">Analyze the following content: {input.content}</Message>
    </Agent>
  )
}

Conditions

⚠️ Experimental: <Condition /> is experimental and might change in future versions.

Use <Condition> to conditionally render agent components based on state or natural language intent. Conditions support both boolean and natural language evaluation:

function AuthAgent() {
  const [isAuthenticated, setIsAuthenticated] = useState(false)
  const [isPremium, setIsPremium] = useState(false)

  return (
    <Agent provider="anthropic" model="claude-haiku-4-5">
      {/* Boolean condition */}
      <Condition when={!isAuthenticated}>
        <System>Please authenticate first</System>
        <Tools>
          <Tool
            name="authenticate"
            handler={async () => {
              setIsAuthenticated(true)
              return 'Authenticated!'
            }}
          />
        </Tools>
      </Condition>

      <Condition when={isAuthenticated}>
        <System>You are authenticated</System>
        <Tools>
          <Tool name="protected_action" ... />
        </Tools>

        {/* Nested condition - only accessible when authenticated AND premium */}
        <Condition when={isPremium}>
          <System>Premium features enabled</System>
          <Tools>
            <Tool name="premium_feature" ... />
          </Tools>
        </Condition>
      </Condition>

      {/* Natural language condition - evaluated via LLM */}
      <Condition when="user wants to do math or calculations">
        <Tools>
          <Tool name="calculate" ... />
        </Tools>
      </Condition>
    </Agent>
  )
}

Conditions are evaluated before each API call:

• Boolean conditions (when={boolean}) are checked first
• Natural language conditions (when="...") are evaluated via LLM

Prompt Caching

Use cache="ephemeral" on <System> or <Context> components to mark dynamic content that shouldn't be cached.

<Agent provider="anthropic" model="claude-sonnet-4-5">
  {/* Stable instructions - will be cached */}
  <System>You are a helpful assistant. Always be concise and accurate.</System>

  {/* Dynamic context - NOT cached (ephemeral) */}
  <Context cache="ephemeral">
    Current user: {user.name}
    Current time: {new Date().toISOString()}
  </Context>

  <Message role="user">What's my name?</Message>
</Agent>

Compaction Control

For long-running conversations, you can enable automatic message compaction to manage context window usage. When the token threshold is exceeded, the framework automatically summarizes previous messages:

<Agent
  provider="anthropic"
  model="claude-haiku-4-5"
  compactionControl={{
    enabled: true,
    contextTokenThreshold: 100000, // Compact when total tokens exceed this
    model: 'claude-haiku-4-5', // Optional: model to use for summarization
    summaryPrompt: 'Summarize the conversation so far', // Optional: custom prompt
  }}
>
  <System>You are a helpful assistant</System>
  <Message role="user">Start a long conversation...</Message>
</Agent>

CompactionControl options:

• enabled: boolean - Enable/disable compaction
• contextTokenThreshold?: number - Token threshold to trigger compaction (default: 100000)
• model?: Model - Model to use for summarization (defaults to agent's model)
• summaryPrompt?: string - Custom prompt for summarization (optional)

API Reference

run(element, options?)

Runs an agent and returns a result or handle.

// Batch mode
const result: AgentResult = await run(<Agent provider="anthropic">...</Agent>, {
  providers: { anthropic: { client: new Anthropic() } },
})

// Interactive mode
const handle: AgentHandle = await run(<Agent provider="anthropic">...</Agent>, {
  mode: 'interactive',
  providers: { anthropic: { client: new Anthropic() } },
})

Options:

• mode?: 'batch' | 'interactive' - Execution mode (default: 'batch')
• providers?: { anthropic?: { client?: Anthropic }; openai?: { client?: OpenAI } } - Provider client map
  • provider is chosen from <Agent provider=\"...\">
  • if omitted, provider clients are created from environment variables by default

createAI(defaults)

Create a defaults-bound runner so you can use ai.run(...) and ai.createAgent(...).

import OpenAI from 'openai'
import { createAI, Agent, Message } from 'agentry'

const ai = createAI({
  providers: { openai: { client: new OpenAI() } },
})

const result = await ai.run(
  <Agent provider="openai" model="gpt-5-mini">
    <Message role="user">Hello</Message>
  </Agent>,
)

Components

Built-ins are provider-owned exports:

• WebSearch, CodeExecution, MCP from agentry/anthropic or agentry/openai
• Memory from agentry/anthropic

<Agent>

Prop	Type	Description
provider?	'anthropic' | 'openai'	AI provider for this agent
model	string	Provider model id (e.g. claude-sonnet-4-5, gpt-5-mini)
name?	string	Agent identifier
description?	string	Agent description
maxTokens?	number	Max output tokens (default: 4096)
maxIterations?	number	Max tool call iterations (default: 20)
stopSequences?	string[]	Stop sequences
temperature?	number	Sampling temperature (0-1)
stream?	boolean	Enable streaming (default: true)
betas?	string[]	Additional Anthropic beta features to enable
thinking?	ThinkingConfig	Extended thinking config (provider-dependent). Anthropic: { type: 'enabled', budget_tokens: number, interleaved?: boolean }. OpenAI: { type: 'enabled', effort: 'low' | 'medium' | 'high', summary: 'auto' | 'concise' | 'detailed' }. Disable: { type: 'disabled' }.
websocket?	boolean	Enable WebSocket mode for OpenAI (reduces per-turn latency ~40% in multi-tool loops via persistent WebSocket connection
compactionControl?	CompactionControl	Context compaction settings (see below)
onMessage?	(event: AgentStreamEvent) => void	Stream event callback
onComplete?	(result: AgentResult) => void	Completion callback
onError?	(error: Error) => void	Error callback
onStepFinish?	(result: OnStepFinishResult) => void	Step completion callback

CompactionControl:

Field	Type	Description
enabled	boolean	Enable/disable compaction
contextTokenThreshold?	number	Token threshold to trigger (default: 100000)
model?	string	Model for summarization (default: agent's model)
summaryPrompt?	string	Custom summary prompt

<System> / <Context>

Prop	Type	Description
children	ReactNode	Content
cache?	'ephemeral'	Mark as non-cacheable for prompt caching

<Message>

Prop	Type	Description
role	'user' | 'assistant'	Message role
children	ReactNode	Message content

<Tools>

Prop	Type	Description
children	ReactNode	Tool components

<Tool>

Prop	Type	Description
name	string	Tool name
description	string	Description for the model
parameters	ZodSchema	Zod schema for input validation
strict?	boolean	Enable structured outputs (auto-enables beta)
handler	(input, context: ToolContext) => Promise<ToolResult>	Tool handler

<AgentTool>

Prop	Type	Description
name	string	Tool name
description	string	Description for the model
parameters	ZodSchema	Zod schema for input validation
agent	(input) => ReactElement<Agent>	Function returning the Agent

<Condition>

Prop	Type	Description
when	boolean | string	Condition (boolean or NL description evaluated by LLM)
provider?	'anthropic' | 'openai'	Override provider for NL evaluation (first NL condition's override applies to the batch)
model?	AnthropicModel | OpenAIModel	Override model for NL evaluation (defaults to claude-haiku-4-5 / gpt-4.1-mini if not set)
children	ReactNode	Content to render when condition is true

<WebSearch>

Prop	Type	Description
maxUses?	number	Max searches allowed
allowedDomains?	string[]	Restrict to these domains
blockedDomains?	string[]	Block these domains
userLocation?	{ city?: string, region?: string, country?: string, timezone?: string }	Location for localized results

<CodeExecution>

No props. Enables sandboxed code execution.

<Memory>

Prop	Type	Description
onView?	(input: { path: string, view_range?: [number, number] }) => Promise<string>	View file/directory handler
onCreate?	(input: { path: string, file_text: string }) => Promise<string>	Create file handler
onStrReplace?	(input: { path: string, old_str: string, new_str: string }) => Promise<string>	Replace text handler
onInsert?	(input: { path: string, insert_line: number, insert_text: string }) => Promise<string>	Insert text handler
onDelete?	(input: { path: string }) => Promise<string>	Delete file handler
onRename?	(input: { old_path: string, new_path: string }) => Promise<string>	Rename/move handler

<MCP>

Prop	Type	Description
name	string	Server name
url	string	SSE endpoint URL
authorization_token?	string	Auth token
tool_configuration?	{ enabled?: boolean, allowed_tools?: string[] }	Tool filtering config

Hooks

Hook	Returns	Description
useExecutionState()	AgentState	Current execution state
useMessages()	AgentMessageParam[]	Conversation messages
useAgentState()	AgentStoreState	Full agent state

AgentHandle (Interactive Mode)

Method / Property	Type	Description
sendMessage(content)	(string) => Promise<AgentResult>	Send a message and get response
stream(message)	(string) => AsyncGenerator<AgentStreamEvent, AgentResult>	Stream a response
run(firstMessage?)	(string?) => Promise<AgentResult>	Run agent to completion
abort()	() => void	Abort current execution
close()	() => void	Clean up resources
state	AgentState	Current execution state
messages	AgentMessageParam[]	Conversation history
isRunning	boolean	Whether agent is processing

Utilities

Function	Description
defineTool(options)	Define a tool programmatically. Options: name, description, parameters, strict?, handler
defineAgentTool(options)	Define a subagent tool. Options: name, description, parameters, agent
createAgent(element, options?)	Create an agent handle without running

ToolContext

Tool handlers receive a context object:

Property	Type	Description
agentName	string	Name of the current agent
provider	'anthropic' | 'openai'	Current provider
client?	Anthropic | OpenAI	Current provider client
clients?	{ anthropic?: Anthropic; openai?: OpenAI }	Provider client map
model?	string	Current agent's model
signal?	AbortSignal	Abort signal for cancellation
metadata?	JsonObject	Custom JSON-like metadata
runAgent	(agent: ReactElement, options?: RunAgentOptions) => Promise<AgentResult>	Run an agent programmatically

RunAgentOptions:

Field	Type	Description
provider?	'anthropic' | 'openai'	Override provider
clients?	{ anthropic?: Anthropic; openai?: OpenAI }	Override client map
model?	string	Override parent's model
maxTokens?	number	Override max tokens
temperature?	number	Override temperature
signal?	AbortSignal	Custom abort signal

Requirements

• Node.js 18+ or Bun
• React 19+
• TypeScript 5+
• Provider API key(s): Anthropic and/or OpenAI

Development

bun install
bun run typecheck
bun test

FAQ

Why call it "Agentry"?

Agent 🤖 + Gantry 🏗️

Why make this?

I wanted to build an AI Agent and was exploring different ways to represent one. I started sketching it out in React and realized the component model made composition and structure really intuitive. React's concepts like hooks, lifecycles, and state made developing the functionality straightforward. Since I wanted it to feel just like writing React, it was the perfect excuse to dig into how the React Reconciler works under the hood and how I could use it for this project.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.