Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
e299fef
Add ai.ModelLike
anbuzin Nov 6, 2026
0d5204a
Implement ai.workers with Codex
anbuzin Nov 9, 2026
7f27cfe
Add Claude Code and Pi workers
anbuzin Nov 9, 2026
ae4c1be
Refactor ai.workers: isolate wires, worker quirks, and stream()
anbuzin Nov 9, 2026
2b1b3ff
Split ai.workers into Worker, WorkerProvider and Session
anbuzin Nov 10, 2026
9f2fcea
Make worker model calls work without a session block
anbuzin Nov 10, 2026
ba62528
Add worker examples ported from the harness examples
anbuzin Nov 10, 2026
19bb8ae
Address the review of ai.workers: names, ai.workers, ModelLike in mod…
anbuzin Nov 13, 2026
946d024
Move the JSON-RPC peer to workers/_jsonrpc.py
anbuzin Nov 16, 2026
57bd861
Add the fx worker
anbuzin Nov 16, 2026
839f4da
Name fx in the shared worker notes
anbuzin Nov 16, 2026
146dab0
Rename ai.workers to ai.external and Worker to ExternalHarness
anbuzin Nov 16, 2026
8f47c18
Rename the worker samples to external in run-examples.py
anbuzin Nov 17, 2026
d0dffe8
Make a model call of an external harness need an open session
anbuzin Nov 17, 2026
a2ed058
Remove session_id from ExternalHarness
anbuzin Nov 17, 2026
a0ddc06
Make Session.start() need an open session
anbuzin Nov 17, 2026
f6669b6
Use the asyncio subprocess API in the external examples
anbuzin Nov 17, 2026
182f65e
Assert the class that a saved external harness loads as
anbuzin Nov 17, 2026
0073da8
Give _sdk() in the Claude Code wire its return type
anbuzin Nov 17, 2026
937516d
Give an external harness its session, and make it a dataclass
anbuzin Nov 17, 2026
0b040a2
Address the review of the external harness examples
anbuzin Nov 17, 2026
8cb302b
Authenticate external harness MCP bridges
anbuzin Nov 17, 2026
a268093
Preserve filtered tool results in external handoffs
anbuzin Nov 17, 2026
f6ed42c
Create seeded external transcripts with private permissions
anbuzin Nov 17, 2026
5edbdeb
Respect the Claude config directory when resuming sessions
anbuzin Nov 17, 2026
bd44c9a
Record external replies before telemetry can yield
anbuzin Nov 17, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions examples/.test_scripts/run-examples.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@
uv run examples/.test_scripts/run-examples.py --image # also image samples
uv run examples/.test_scripts/run-examples.py --video # also video samples
uv run examples/.test_scripts/run-examples.py --e2e # also e2e test scripts
uv run examples/.test_scripts/run-examples.py --external
# also external samples: need logged-in `claude`, `codex` and `fx` CLIs
uv run examples/.test_scripts/run-examples.py --all # everything
uv run examples/.test_scripts/run-examples.py --parallel # in parallel
uv run examples/.test_scripts/run-examples.py models/stream.py
Expand Down Expand Up @@ -74,6 +76,22 @@ class Sample:
Sample("media/speech_generation.py"),
]

# These drive real coding-agent CLIs, so --model and --protocol do not apply
# to the external harness. The CLIs must be installed and logged in.
EXTERNAL_SAMPLES: list[Sample] = [
Sample("external/basic.py", timeout=300.0),
Sample("external/streaming.py", timeout=300.0),
Sample("external/agent_tools.py", timeout=300.0),
Sample("external/direct_control.py", timeout=300.0),
Sample("external/steering.py", timeout=300.0),
Sample("external/resume.py", timeout=300.0),
Sample("external/combine.py", timeout=300.0),
Sample("external/as_tool.py", timeout=300.0),
Sample("external/custom_loop.py", timeout=300.0),
Sample("external/until_done.py", timeout=600.0),
Sample("external/handoff.py", timeout=600.0),
]

BROKEN_SAMPLES: list[Sample] = []

# E2E tests pick non-default ports so they don't collide with a running
Expand Down Expand Up @@ -104,6 +122,7 @@ class Sample:
*IMAGE_SAMPLES,
*VIDEO_SAMPLES,
*AUDIO_SAMPLES,
*EXTERNAL_SAMPLES,
*BROKEN_SAMPLES,
*E2E_TESTS,
]
Expand Down Expand Up @@ -248,6 +267,11 @@ def main() -> None:
parser.add_argument(
"--audio", action="store_true", help="include audio samples"
)
parser.add_argument(
"--external",
action="store_true",
help="include external harness samples (real claude/codex CLIs)",
)
parser.add_argument(
"--broken", action="store_true", help="include broken samples"
)
Expand Down Expand Up @@ -290,6 +314,7 @@ def main() -> None:
or args.image
or args.video
or args.audio
or args.external
or args.broken
or args.e2e
)
Expand All @@ -310,6 +335,8 @@ def main() -> None:
samples.extend(VIDEO_SAMPLES)
if not args.examples and (args.audio or args.all):
samples.extend(AUDIO_SAMPLES)
if not args.examples and (args.external or args.all):
samples.extend(EXTERNAL_SAMPLES)
if not args.examples and (args.broken or args.all):
samples.extend(BROKEN_SAMPLES)
if not args.examples and (args.e2e or args.all):
Expand Down
3 changes: 3 additions & 0 deletions examples/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,9 @@ Examples are grouped by the main API surface they demonstrate.
- `media/` contains image, video, speech, transcription, multimodal, embedding,
and reranking examples.
- `models/` contains model streaming, structured output, and provider examples.
- `external/` contains examples that use coding-agent CLIs (Claude Code, Codex,
fx, pi) where a model goes (experimental; run with
`run-examples.py --external`).

Provider-specific model examples live under `models/<provider>/`, such as
`models/gateway/`, `models/openai/`, and `models/anthropic/`.
Expand Down
2 changes: 2 additions & 0 deletions examples/apps/durable_agent_temporal/backend/app/worker.py
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,8 @@ class DurableAgent(ai.Agent):
async def loop(self, context: ai.Context) -> AsyncGenerator[ai.events.AgentEvent]:
tools_data = [tool.model_dump(mode="json") for tool in context.tools]

# A durable step serializes the model: it must be an ai.Model.
assert isinstance(context.model, ai.Model)
while context.keep_running():
result = await temporalio.workflow.execute_activity(
llm_activity,
Expand Down
2 changes: 2 additions & 0 deletions examples/apps/durable_agent_workflows/backend/app/worker.py
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,8 @@ class DurableAgent(ai.Agent):
async def loop(self, context: ai.Context) -> AsyncGenerator[ai.events.AgentEvent]:
tools_data = [tool.model_dump(mode="json") for tool in context.tools]

# A durable step serializes the model: it must be an ai.Model.
assert isinstance(context.model, ai.Model)
while context.keep_running():
result = await llm_step(
context.model.model_dump(mode="json"),
Expand Down
Empty file added examples/external/__init__.py
Empty file.
33 changes: 33 additions & 0 deletions examples/external/agent_tools.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
"""An ai.Agent gives its Python tools to a CLI, through the MCP bridge."""

import asyncio

import ai


@ai.tool
async def secret_word(topic: str) -> str:
"""Return the secret word for a topic."""
return {"birds": "HERON"}.get(topic, "UNKNOWN")


async def main() -> None:
agent = ai.Agent(tools=[secret_word])
messages = [
ai.user_message(
"Use the secret_word tool for the topic 'birds'. "
"Reply with the word only."
)
]
async with ai.external.Fx() as harness, agent.run(harness, messages) as run:
async for event in run:
match event:
case ai.events.ToolEnd(): # an ai tool: the agent runs it
print(f"[ai tool] {event.tool_call.tool_name}")
case ai.events.TextDelta():
print(event.chunk, end="", flush=True)
print()
print([message.role for message in run.messages])


asyncio.run(main())
61 changes: 61 additions & 0 deletions examples/external/as_tool.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
"""A coding-agent CLI as a tool: the external harness is a sub-agent."""

import asyncio
import tempfile

import ai

model = ai.get_model("anthropic/claude-sonnet-4.6")


async def main() -> None:
with tempfile.TemporaryDirectory() as tmp:
# One block for the whole run: each call of the tool continues the
# same conversation, on one live CLI.
async with ai.external.ClaudeCode(cwd=tmp) as harness:
# The external harness's events stream up as partial tool results,
# and its last text becomes the tool result. To close the parent run
# stops the external harness's turn too.
@ai.tool
async def code(task: str) -> ai.SubAgentTool:
"""Do a coding task in the project; returns what was done."""
messages = [
*harness.session.messages,
ai.user_message(task),
]
async with ai.stream(harness, messages) as stream:
async for event in stream:
yield event

orchestrator = ai.Agent(tools=[code])

messages = [
ai.system_message(
"You plan; the code tool writes the code. Summarize the "
"result for the user in one sentence."
),
ai.user_message(
"Create hello.py that prints 'hello', then run it."
),
]

async with orchestrator.run(model, messages) as stream:
async for event in stream:
match event:
case ai.events.PartialToolCallResult(
value=ai.events.BuiltinToolEnd(tool_call=call)
):
# The external harness at work, inside the tool
# call.
print(f" [external harness] {call.tool_name}")
case ai.events.TextDelta():
print(event.chunk, end="", flush=True)
print()

# The session has the external harness's own conversation.
count = len(harness.session.messages)
print(f"external harness messages: {count}")


if __name__ == "__main__":
asyncio.run(main())
30 changes: 30 additions & 0 deletions examples/external/basic.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
"""Simplest external harness: one prompt to a CLI, where a model goes."""

import asyncio

import ai


async def main() -> None:
messages = [ai.user_message("Reply with exactly: READY")]

async with (
ai.external.ClaudeCode() as harness,
ai.stream(harness, messages) as stream,
):
async for event in stream:
match event:
case ai.events.TextDelta():
print(event.chunk, end="", flush=True)
case ai.events.StreamEnd():
print(f"\nfinish: {event.finish_reason}")

if stream.usage is not None:
print(
f"tokens: {stream.usage.input_tokens} in / "
f"{stream.usage.output_tokens} out"
)


if __name__ == "__main__":
asyncio.run(main())
47 changes: 47 additions & 0 deletions examples/external/combine.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
"""Run two external harnesses at the same time and read them as one stream."""

import asyncio
import tempfile
from collections.abc import AsyncGenerator

import ai


async def tagged(
label: str, cwd: str, prompt: str
) -> AsyncGenerator[tuple[str, ai.events.Event]]:
async with (
ai.external.ClaudeCode(cwd=cwd) as harness,
ai.stream(harness, [ai.user_message(prompt)]) as stream,
):
async for event in stream:
yield label, event


async def main() -> None:
with tempfile.TemporaryDirectory() as tmp:
# One external harness is one conversation: two at a time are two
# external harnesses, one in each stream.
async with ai.util.merge(
tagged(
"poem",
tmp,
"Write a two-line poem about rivers into poem.txt.",
),
tagged(
"limerick",
tmp,
"Write a limerick about mountains into limerick.txt.",
),
) as events:
async for label, event in events:
match event:
case ai.events.BuiltinToolEnd():
print(f"[{label}] {event.tool_call.tool_name}")
case ai.events.StreamEnd():
print(f"[{label}] done ({event.finish_reason})")
print(f"[{label}] {event.message.text.strip()}")


if __name__ == "__main__":
asyncio.run(main())
99 changes: 99 additions & 0 deletions examples/external/custom_loop.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
"""Custom loop: an external harness turn as one step of your own agent loop."""

import asyncio
import pathlib
import tempfile
from collections.abc import AsyncGenerator

import ai

REASONING = (
ai.events.ReasoningStart,
ai.events.ReasoningDelta,
ai.events.ReasoningEnd,
)


class CodeThenReview(ai.Agent):
def __init__(self, cwd: str) -> None:
super().__init__()
self.cwd = cwd

async def loop(
self, context: ai.Context
) -> AsyncGenerator[ai.events.AgentEvent]:
"""The external harness does the task, then the model reviews it."""
# Step 1: the external harness does the task. Each run is a new
# conversation: a new external harness.
async with (
ai.external.ClaudeCode(cwd=self.cwd) as harness,
ai.stream(harness, [context.messages[-1]]) as work,
):
async for event in work:
if not isinstance(event, REASONING):
yield event

# Step 2: evidence from the directory, not the external harness's word
# for it. Only the external harness's answer joins the agent's context,
# not its tool calls: they name tools that this model does not have.
source = pathlib.Path(self.cwd, "hello.py").read_text()
process = await asyncio.create_subprocess_exec(
"python3",
"hello.py",
cwd=self.cwd,
stdout=asyncio.subprocess.PIPE,
stderr=asyncio.subprocess.DEVNULL,
)
try:
async with asyncio.timeout(30):
stdout, _ = await process.communicate()
except TimeoutError:
process.kill()
raise
context.add(ai.assistant_message(work.text))
context.add(
ai.user_message(
"You are the reviewer. hello.py contains:\n"
+ source
+ f"\nRunning it printed: {stdout.decode().strip()!r} "
+ f"(exit code {process.returncode}).\n"
+ "In one sentence: does it meet the task? Start with YES "
+ "or NO."
)
)

# Step 3: a model call, like any other agent step.
async with ai.stream(context=context) as review:
async for event in review:
yield event
context.add(review.message)


async def main() -> None:
model = ai.get_model("anthropic/claude-sonnet-4.6")

with tempfile.TemporaryDirectory() as tmp:
my_agent = CodeThenReview(tmp)

async with my_agent.run(
model,
[
ai.user_message(
"Create hello.py that prints 'hello', then run it."
)
],
) as stream:
async for event in stream:
match event:
case ai.events.BuiltinToolEnd():
print(f"[external harness] {event.tool_call.tool_name}")
case ai.events.TextDelta():
print(event.chunk, end="", flush=True)
case ai.events.StreamEnd():
print()

print(f"review: {stream.output}")


if __name__ == "__main__":
asyncio.run(main())
Loading
Loading