Agent¶

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.

When to use plain `Agent`¶

Use plain `Agent` when…	Use a deep agent when…
The task fits in one linear pass of "tool → tool → answer".	The task needs explicit planning or multi-step decomposition.
Latency matters more than perfect output.	Quality matters more than latency.
You want minimal ceremony.	You want self-verification, reflection, or sub-agent delegation.
You're building chat features, simple Q&A, or quick automations.	You're building research, code generation, or long-horizon workflows.

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¶

Need	Pass	Docs
Tools	`tools=[…]` or `with_builtins()`	Custom tools
Skills	`skills=[…]`, `default_skill_ids=[…]`, `skill_source=…`	Skills guide
MCP servers	`mcps=[…]`	MCP integration
Grounded answers with citations	`rag=my_rag`	RAG + Agent
Long-term memory	`memory_store=…`	Advanced memory
Multi-turn chat	`session_store=…` + `agent.chat_session(…)`	Sessions guide
Audit trail	`trace_store=…`	FAQ — production
Hooks (before/after LLM, tool wrappers)	`hooks=AgentHooks(…)`	Hooks guide
Parallel tool calls	`parallel_tool_execution=True`	Parallel execution
Auto context compaction	`context_window_tokens=200_000`	Context management
Retry policy	`retry_policy=RetryPolicy(…)`	Error recovery
Higher iteration cap	`max_iterations=20`	Re-planning

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.
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.

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