Overview

shipit_agent.Agent is the core building block of the entire library. Every other agent type — DeepAgent, GoalAgent, ReflectiveAgent, AdaptiveAgent, Supervisor, PersistentAgent — wraps an Agent internally. If you understand Agent, you understand the runtime.

TL;DR — Agent.with_builtins(llm=llm).run(prompt) is the minimum viable agent. Add tools=, rag=, memory_store=, or session_store= as you need them.

New in 1.7 — the working set

The 1.7 line is about doing the most with the fewest tokens: reach for a tool only when the turn needs it, keep the rest out of the request until it does, and hand the model what it needs directly instead of making it fetch.

Deferred tool loading

A small core set keeps its schema in every request; everything else — including MCP tools — is listed by name only until tool_search (or a direct call) pages it in. On a many-tool or MCP-heavy turn, the fixed per-step schema cost drops to just the working set.

from shipit_agent import Agent

# Core tools stay resident; the rest are name-only until needed.
agent = Agent(llm=llm, tools=tools, deferred_tools=True)

agent.run("Find the failing test and open a fix PR")
# The agent tool_searches for what this task needs and loads only that.

Files and images, straight to the model

Attach media to the turn — on run() and stream(). No read-it-yourself round-trip. Text, markdown and code inline on every provider; PDFs ride as native document blocks where the provider reads them; images need a vision-capable model.

result = agent.run(
    "What changed between these, and does the error match the log?",
    images=["before.png", "after.png"],   # url, path, or base64
    files=["report.pdf", "server.py", "trace.log"],
)

Native structured output

Hand Agent a schema and the run returns that type, validated — on providers that support response formats, with a prompt-and-validate fallback everywhere else.

from pydantic import BaseModel

class Incident(BaseModel):
    severity: str
    root_cause: str
    affected_files: list[str]

result = agent.run("Triage the crash in yesterday's logs", output_type=Incident)
if result.output.severity == "critical":
    page_oncall(result.output.root_cause)

Live streaming, everywhere

Streaming is the default surface, not a debug mode. Every step, tool input/output delta, and a per-run decision narration streams as it happens — render it in a CLI, a web UI, or a log sink.

for event in agent.stream("Upgrade pydantic and fix the fallout"):
    if event.type == "tool_call":
        print(f"→ {event.tool}({event.summary})")
    elif event.type == "text_delta":
        print(event.delta, end="", flush=True)

Also new in 1.7: parallel, read-safe tools (read-only groups fan out, writes stay serial), powerful sub-agents with toolset containment, prompt caching across the system prompt, tools, and conversation prefix, and MCP hardening — tool-name sanitization for every server, per-request timeouts, and respawn re-handshake. See the changelog.

When to use plain Agent

The rule of thumb: start with Agent. When the task starts to feel too long for a single linear run, switch to DeepAgent — you keep all the same tools and gain planning, workspace, sub-agent delegation, and the option to enable verification or reflection with one extra flag.

Quick start

from shipit_agent import Agent
from examples.run_multi_tool_agent import build_llm_from_env

llm = build_llm_from_env()             # reads SHIPIT_LLM_PROVIDER from .env
agent = Agent.with_builtins(llm=llm)   # 30+ built-in tools, ready to go

result = agent.run("Find today's Bitcoin price in USD from a reputable source.")
print(result.output)

with_builtins() ships ~30 tools out of the box: web search, browser automation, code execution, file workspace, Slack, Gmail, Jira, Linear, Notion, Confluence, and more.

Streaming

Replace agent.run(...) with agent.stream(...) to watch each step happen live:

for event in agent.stream("Find today's BTC price."):
    print(f"[{event.type}] {event.message}")

You'll see run_started, step_started, reasoning_started, reasoning_completed, tool_called, tool_completed, run_completed events as they happen — not buffered until the end. Every event is a plain dataclass; render them however your UI wants.

See the Streaming guide for the full event reference and the Examples page for a colored terminal renderer you can copy.

Composition checklist

Every parameter is documented with type, default, and "use it when" in the Parameters Reference.

What's in this section

• Examples — Hello-world, web search, custom tools, multi-turn chat, parsers, structured output.
• Streaming — Real-time event handling with rendering recipes for terminals, notebooks, and SSE/WebSocket transports.
• Structured output — typed Pydantic / JSON-Schema results with same-conversation validation retry and streaming partial JSON.
• Verifier network — second cheap LLM vetoes hallucinated tool calls and detects stalling.
• Episodic memory consolidation — distill conversations into durable facts; forgetting curve + core memory promotion. ChatGPT-style memory, principled.
• Time-travel replay — load any saved trace, fork from any event, edit the prompt, resume on a fresh agent. Replay.io for AI agents.
• ComputerUseAgent — drive a browser by showing screenshots to a vision-capable LLM. Anthropic native computer-use + plain-text fallback for any vision LLM. Mock browser for unit tests, Playwright for production.
• Multimodal chat — users paste image, audio, video, or PDF references inline ([url], ![alt](/docs/agent/docs/agent/url), [media:uuid]) anywhere in their prompt. The agent extracts each reference, builds an Anthropic-shape multimodal message, and the vision LLM sees the asset in context.
• With RAG — Wire a knowledge base into an Agent with one parameter and read citations off result.rag_sources.
• With Tools — Extend the agent with custom tools, MCP servers, and runtime tool factories.
• Skills — attach packaged skills, custom catalogs, and runtime-managed skill workflows.
• Memory — AgentMemory, conversation summaries, semantic facts, entity tracking, and the OpenAI-style "remember things across sessions" pattern.
• Sessions & Memory — Persistent multi-turn chat, long-term memory, and conversation forking.
• Tracing — Record every event from a run into FileTraceStore or InMemoryTraceStore and inspect the full timeline later — your local LangSmith.

For agentic patterns above plain Agent (planning, reflection, delegation, goal-driven), see the Deep Agents section.

See also

• Quickstart — five-minute tour
• DeepAgent — when you need more than plain Agent
• Parameters Reference — every constructor parameter
• FAQ — agent types — pick the right agent for the task