Quickstart

This guide walks you through building a research agent with opentine from scratch. By the end, you'll have a working agent that searches the web, synthesizes findings, and produces a report — with every step saved and forkable.

1. Install opentine

Install opentine with the Anthropic model adapter. Python 3.11+ is required.

Terminal
pip install "opentine[anthropic]"

See the Installation guide for other model providers and installation options.

2. Set Your API Key

Export your Anthropic API key so the model adapter can authenticate.

Terminal
export ANTHROPIC_API_KEY="sk-ant-..."

3. Write Your Agent

Create a new file and define your agent. The Agent constructor takes a model adapter, a list of tools, an optional system prompt, and an optional step limit.

research.py
1from opentine import Agent
2from opentine.models.anthropic import Anthropic
3from opentine.tools.web import search, fetch
4from opentine.tools.fs import read, write
5
6agent = Agent(
7    model=Anthropic("claude-sonnet-4-20250514"),
8    tools=[search, fetch, read, write],
9    system="You are a research assistant. Search the web, synthesize findings, and write a report.",
10    max_steps=30,
11)
12
13# Run the agent (async version also available via agent.run())
14run = agent.run_sync("Research the current state of solid-state batteries")
15
16# Print results
17print(f"Completed in {run.total_duration:.1f}s")
18print(f"Total cost: {run.total_cost:.4f}")
19print(f"Steps taken: {len(run.root_steps())}")

The Agent class records every step the model takes — tool calls, thinking, model responses — into a run tree. Nothing is lost.

4. Run It

Execute your script. The agent will search the web, fetch pages, synthesize information, and write a report. Every step is automatically recorded in the run tree.

Terminal
python research.py

5. Save the Run

After the agent finishes, save the entire run tree to a .tine file. This captures every step, its inputs, outputs, costs, and timing.

research.py
# Save the full run tree to a .tine file
run.save("battery_research.tine")

6. Inspect with tine show

Use the CLI to view the run tree. You'll see every step the agent took, how long each one took, and how much it cost.

Terminal
# View the run tree in your terminal
tine show battery_research.tine

Example output:

Terminal
Run: battery_research
Status: completed | Steps: 12 | Cost: $0.0341 | Duration: 18.7s

[think]  Planning research approach...
[tool]   search("solid-state battery 2026 breakthroughs")
[model]  Analyzing 8 search results...
[tool]   fetch("https://example.com/solid-state-review")
[tool]   fetch("https://example.com/toyota-battery-update")
[model]  Synthesizing findings...
[tool]   write("battery_report.md")
[done]   Report written to battery_report.md

7. Fork from Any Step

The real power of opentine: when step 6 went wrong, you don't re-run the first 5 steps. You fork from step 5 and try a different approach. No wasted tokens, no wasted time.

Terminal
# Fork from step 5 to try a different synthesis approach
tine fork battery_research.tine --from step_abc123 --out battery_v2.tine

You can also fork programmatically in Python:

fork_run.py
1from opentine import Run
2
3# Load the saved run
4run = Run.load("battery_research.tine")
5
6# Fork from a specific step to try a different approach
7forked = run.fork(from_step_id="step_abc123", new_run_id="battery_v2")
8
9# The forked run has all steps up to the fork point
10# You can now resume it with a modified agent or prompt

Using Async

The Agent class supports both sync and async execution. Useagent.run() for async or agent.run_sync() for sync.

async_research.py
1import asyncio
2from opentine import Agent
3from opentine.models.anthropic import Anthropic
4from opentine.tools.web import search, fetch
5
6async def main():
7    agent = Agent(
8        model=Anthropic("claude-sonnet-4-20250514"),
9        tools=[search, fetch],
10    )
11
12    run = await agent.run("Research the latest advances in quantum computing")
13    run.save("quantum_research.tine")
14
15asyncio.run(main())

Next Steps

  • Learn about Run Trees and how steps are organized
  • Explore the built-in Tools for web, filesystem, shell, and Python execution
  • Set up different Models — OpenAI, Google, Ollama, and more
  • Understand Serialization and the .tine file format
  • Master Forking to branch and experiment with agent runs