shipit_agent

<p align="center"> <img src="banner.svg" alt="SHIPIT Agent — production-grade Python agent runtime" width="100%" /> </p> <p align="center"> <img src="shipit-icon.svg" alt="SHIPIT" width="120" height="120" /> </p> <h1 align="center">SHIPIT Agent</h1> <p align="center"> <strong>A clean, powerful, open-source Python runtime for building tool-using AI agents.</strong> </p> <p align="center"> <em>One consistent API over every major LLM provider — with tools, skills, memory, MCP, a rule-based permission layer, prompt caching, deep multi-agent orchestration, RAG, and structured streaming events.</em> </p> <p align="center"> <a href="https://docs.shipiit.com/"><strong>📖 Documentation</strong></a> · <a href="https://pypi.org/project/shipit-agent/"><strong>📦 PyPI</strong></a> · <a href="https://docs.shipiit.com/getting-started/quickstart/">Quick start</a> · <a href="CHANGELOG.md">Changelog</a> · <a href="SECURITY.md">Security</a> </p> <p align="center"> <a href="https://pypi.org/project/shipit-agent/"><img src="https://img.shields.io/pypi/v/shipit-agent?style=for-the-badge&color=blue&label=pypi&cacheSeconds=300" alt="PyPI" /></a> <a href="https://pypi.org/project/shipit-agent/"><img src="https://img.shields.io/pypi/pyversions/shipit-agent?style=for-the-badge&color=green&cacheSeconds=300" alt="Python versions" /></a> <a href="https://pypi.org/project/shipit-agent/"><img src="https://img.shields.io/pypi/dm/shipit-agent?style=for-the-badge&color=purple&label=downloads&cacheSeconds=300" alt="Downloads" /></a> <a href="LICENSE.md"><img src="https://img.shields.io/badge/license-MIT-yellow?style=for-the-badge" alt="License" /></a> <a href="https://docs.shipiit.com/"><img src="https://img.shields.io/badge/docs-mkdocs--material-483D8B?style=for-the-badge" alt="Docs" /></a> </p> <p align="center"> <img src="https://img.shields.io/badge/Anthropic-native-D77757?style=flat-square&logo=anthropic" alt="Anthropic" /> <img src="https://img.shields.io/badge/AWS%20Bedrock-supported-orange?style=flat-square&logo=amazon-aws" alt="Bedrock" /> <img src="https://img.shields.io/badge/OpenAI-supported-412991?style=flat-square&logo=openai" alt="OpenAI" /> <img src="https://img.shields.io/badge/Gemini-supported-4285F4?style=flat-square&logo=google" alt="Gemini" /> <img src="https://img.shields.io/badge/Vertex%20AI-supported-34A853?style=flat-square&logo=googlecloud" alt="Vertex AI" /> <img src="https://img.shields.io/badge/Groq-supported-red?style=flat-square" alt="Groq" /> <img src="https://img.shields.io/badge/Together%20AI-supported-blue?style=flat-square" alt="Together" /> <img src="https://img.shields.io/badge/Ollama-supported-black?style=flat-square" alt="Ollama" /> <img src="https://img.shields.io/badge/LiteLLM-100%2B%20models-success?style=flat-square" alt="LiteLLM" /> </p>

---

<p align="center"> <a href="https://www.youtube.com/watch?v=1_xFvZDC7xg"> <img src="https://img.youtube.com/vi/1_xFvZDC7xg/maxresdefault.jpg" alt="Watch: SHIPIT Agent — a clean, powerful Python runtime for tool-using AI agents" width="70%" /> </a> </p> <p align="center"> <a href="https://www.youtube.com/watch?v=1_xFvZDC7xg"><strong>▶ **Shipt Agent UI**| Watch the intro </strong></a> </p>

---

What is SHIPIT Agent?

SHIPIT Agent is a small, explicit runtime for building production agents in Python. You bring an LLM; the runtime gives you the loop around it — tool calling, retries, streaming, memory, sessions, permissions, and cost tracking — plus a deep library of batteries (40+ built-in tools, 17 SaaS connectors, RAG, multi-agent orchestration, browser automation).

It is provider-agnostic by design: the same agent code runs on OpenAI, Anthropic, AWS Bedrock, Google Vertex/Gemini, Groq, Together, Ollama, or any of 100+ models through LiteLLM. Swap the model in one line — nothing else changes.

from shipit_agent import Agent
from shipit_agent.llms import build_llm_from_env

agent = Agent.with_builtins(llm=build_llm_from_env())   # any provider
print(agent.run("Find every TODO in this repo and summarize them.").output)

The only hard dependency is pydantic. Everything else (a provider SDK, Playwright, a vector store) is an optional extra you install when you need it. Python 3.11+ · MIT · 3,500+ tests.

---

Highlights

• 🤖 The Agent — one runtime: tool calling, retries, parallel tools, context compaction, and a final-answer guarantee. Agent.with_builtins() ships the full tool catalogue.
• 🔌 Any LLM — OpenAI · Anthropic · Bedrock · Vertex · Gemini · Groq · Together · Ollama · OpenRouter · 100+ via LiteLLM. Native adapters where it matters, one interface everywhere.
• 🛡️ Control plane — a fast, rule-based permission engine (allow/deny/ask), plan mode (read-only research before acting), and hooks that can block or rewrite any tool call.
• ⚡ Prompt caching — cross-provider cache-read accounting (Anthropic/Bedrock/Vertex cache_control + OpenAI automatic caching) so repeated calls bill at a fraction of the cost.
• 🧰 Tools & connectors — 40+ built-in tools (bash, SQL, files, web search, code execution, vision, PDF…) and 17 SaaS connectors (GitHub, Slack, Gmail, Jira, Salesforce, Stripe…).
• 🔗 MCP — connect Model Context Protocol servers over stdio, HTTP, or a persistent subprocess.
• 🧠 Deep agents — GoalAgent, ReflectiveAgent, Supervisor/Worker, ShipCrew, and the create_deep_agent() factory for autonomous, multi-step, multi-agent work.
• 📚 Super RAG — hybrid vector + BM25 search with auto-cited sources and pluggable backends (Chroma, Qdrant, pgvector).
• 🚀 Autopilot — long-running autonomous loops with a critic, artifacts, fan-out, and a scheduler.
• 🖥️ Computer use — drive a real browser via screenshots + a vision model (works in Jupyter).
• 📊 Production-ready — sessions, memory consolidation, structured output with validation-retry, streaming events (+ SSE/WebSocket packets), tracing (file/OTel/LangSmith), and budgets.

---

What's new in v1.9.6 — fewer tokens, steadier connectors

• Calibrated context accounting (v1.9.5) — compaction now fires at the right time. The trigger learns each model's real tokens-per-char from the provider's reported usage (TokenCalibrator) and counts the fixed prompt prefix (system + tool schemas), instead of a flat chars/4 that under-counted dense tool output by multiples. Result: long, tool-heavy runs stay lean and stop overflowing the model. Clamped so it can only ever compact earlier, never later.
• MCP resilience (v1.9.6) — a per-server circuit breaker + bounded retry (ResilientMCPTransport). A connector that is down or rate-limiting (HTTP 429 / JSON-RPC -32029) fails fast instead of waiting out the full timeout on every step, so one flaky server can't tax the whole agent. A success resets it.

Both are backwards compatible and covered by the test suite. See the changelog.

---

Automatic tool discovery

Ordinary Agent(llm=llm, tools=tools, mcps=servers) now defaults to deferred_tools="auto". Catalogs that fit ten tools and approximately 4,096 schema tokens stay visible. Otherwise, the initial request exposes up to nine working tools plus search_tools, within that schema budget. An existing ToolSearchTool is reused under its configured name.

Core selection prefers a tool's numeric discovery_priority, then Shipit's core capabilities, then registration order. Assign higher priorities to your application's frequently used tools. Up to three recently discovered schemas can be reused within the same session, competing for the same initial slots. Changed schemas and statically denied tools are excluded from reuse; argument permissions are still checked at execution. Session caches are bounded to 32 sessions per Agent instance and are not persisted across process restarts. The model can search descriptions, names, and MCP server metadata; matching tools become callable with their full schemas on the next step. Search does not execute them or grant additional permissions. Loaded tools remain visible for the rest of the run, so ten is an initial budget, not an execution limit.

Auto mode includes a compact capability-family index instead of listing every deferred tool name. Ranking runs locally without additional LLM calls. Exact-name searches load only the named tool; names can use underscores, camelCase or Unicode. Newly loaded schemas append after those already shown. This works through run(), stream(), and the async runtime using ordinary function schemas, including providers without native tool-search support.

Use deferred_tools=False to keep every schema visible, True for the existing core-only policy, or a list of names to defer specific tools. Code mode retains its own discovery policy. Measure total request tokens and task completion in your workload: discovery adds an LLM step, so schema savings are not a promise of equal total-token savings.

See the discovery review and offline benchmark for measured payload reductions and remaining tradeoffs.

Ordinary Agent also supports opt-in progressive_skills=True for metadata-first skill loading and max_task_tokens=50_000 for a soft per-run token threshold. See progressive skills, budget limits and validation for setup, isolation guarantees and provider-usage caveats.

from shipit_agent.deferral import DiscoveryPolicy

agent = Agent(
    llm=llm, tools=tools, mcps=servers,
    deferred_tools=DiscoveryPolicy(initial_tools=10, schema_tokens=4096, reuse_tools=3),
)

Discovery itself remains visible even if its schema exceeds a very small configured budget. Definitions loaded during a run are not evicted mid-run. For large structured results, tools may return ToolOutput.from_records(rows, fields=["id", "evidence"], limit=20). The model receives an explicit page and total count; callers retain the full JSON. This is context reduction, not security redaction.

Run summaries distinguish finished from incomplete provider output, expose finish reasons, failed-tool counts, and recovery counts. finished means the runtime ended normally, not that an independent grader verified the answer. Provider-reported usage counters remain unchanged; cache ratios and cost estimates account for whether cached tokens are included in prompt tokens.

An opt-in, billed multi-turn evaluation is available in scripts/evaluate_agent_session.py. It uses safe fixture tools and an in-process MCP server, not production data or production MCP transport.

What's new in v1.7.0 — the working set

The biggest capability release yet: do the powerful thing without burning tokens or trust. All of it works with any LLM provider.

from shipit_agent import Agent

# 1. Deferred tool loading — a small core stays resident; the rest (and MCP
#    tools) are listed by name and loaded on demand via tool_search.
agent = Agent.with_builtins(llm=llm, deferred_tools=True)

# 2. Attachments — images, PDFs, and code/markdown files on the turn.
agent.run("What changed here?", images=["diagram.png"], files=["spec.pdf", "app.py"])

# 3. Batch, atomic edits to one file, and a full shell when you want it.
#    multi_edit applies many edits at once; bash gets a 600s ceiling,
#    an unrestricted mode, and a bash_job companion to poll/kill jobs.

# 4. Structured output straight from the provider (no parse-retry needed).
agent.run("Extract the invoice", output_schema=InvoiceSchema)

# 5. Plan mode as a workflow — the agent researches read-only, then submits a
#    structured plan for approval before it acts.

Plus: read parallelization (read-only tools fan out, writes stay ordered), prompt caching across the conversation prefix, compaction re-grounding (re-reads files after summarizing), MCP hardening (name sani