SHIPIT

Overview

The core shipit_agent.Agent class — what it is, when to use it, and how to compose it with tools, RAG, memory, and sessions.

3 min read
6 sections
Edit this page

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

python
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:

python
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

NeedPassDocs
Toolstools=[…] or with_builtins()Custom tools
Skillsskills=[…], default_skill_ids=[…], skill_source=…Skills guide
MCP serversmcps=[…]MCP integration
Grounded answers with citationsrag=my_ragRAG + Agent
Long-term memorymemory_store=…Advanced memory
Multi-turn chatsession_store=… + agent.chat_session(…)Sessions guide
Audit trailtrace_store=…FAQ — production
Hooks (before/after LLM, tool wrappers)hooks=AgentHooks(…)Hooks guide
Parallel tool callsparallel_tool_execution=TrueParallel execution
Auto context compactioncontext_window_tokens=200_000Context management
Retry policyretry_policy=RetryPolicy(…)Error recovery
Higher iteration capmax_iterations=20Re-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.

See also