Loading…
Loading…
Features · Build · Async SDK
shipit_agent.sdk is an async layer on the same agent loop: query() streams typed messages, AgentOptions holds the model, tools and permissions, and a ResultMessage closes every run with its turns and cost.
import asynciofrom shipit_agent.sdk import AgentOptions, AssistantMessage, ResultMessage, TextBlock, queryasync def main() -> None: options = AgentOptions( model="claude-opus-5-5", cwd="/path/to/repo",
AgentOptions
model, tools, permissions
query()
async messages
shipit loop
any provider
ResultMessage
result, turns, cost
The code is a checked example from the docs; the output is an example of what it prints.
import asyncio
from shipit_agent.sdk import AgentOptions, AssistantMessage, ResultMessage, TextBlock, query
async def main() -> None:
options = AgentOptions(
model="claude-opus-5-5",
cwd="/path/to/repo",
allowed_tools=["Read", "Grep", "Bash(pytest *)"],
permission_mode="acceptEdits",
max_budget_usd=2.0,
)
async for message in query(prompt="Fix the failing test in tests/test_api.py", options=options):
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, TextBlock):
print(block.text)
elif isinstance(message, ResultMessage):
print(message.subtype, message.num_turns, message.total_cost_usd)
asyncio.run(main())6 more ways to use it
Each example is from the docs and checked against the library.
External servers use the same `mcp_servers` dict:
from shipit_agent.sdk import AgentOptions, create_sdk_mcp_server, tool
@tool("add", "Add two numbers", {"a": float, "b": float})
async def add(args):
return {"content": [{"type": "text", "text": str(args["a"] + args["b"])}]}
calc = create_sdk_mcp_server("calc", tools=[add])
options = AgentOptions(mcp_servers={"calc": calc}, allowed_tools=["mcp__calc__add"])All 19 model providers
Each built-in provider profile, with its default model, the variable that picks another, and the key it reads.
anthropicazurebedrockcerebrascoheredeepseekfireworksgeminigroqlitellmmistralollamaopenaiopenrouterperplexityshipittogethervertexxaiSame names
query, AgentOptions, messages, hooks, permission rules and sessions.
Custom tools
@tool functions and in-process MCP servers.
Approvals
can_use_tool callbacks and permission rules decide each call.
Any provider
Anthropic, OpenAI, Bedrock, Gemini, Ollama and the rest.
| Parameter | Default | What it does |
|---|---|---|
| allowed_tools | empty | Pre-approved calls, as SDK rules: `"Read"`, `"Bash(npm test *)"`. They approve; they do not restrict the other tools. |
| disallowed_tools | empty | A bare name removes the tool from the run; a scoped rule such as `"Bash(rm *)"` denies matching calls in every permission mode. |
| permission_mode | 'default' | Rule-based gate over tool calls. Set a mode ("default" | "acceptEdits" | "plan" | "bypass"), or pass a full `PermissionEngine` / kwargs dict via `permissions`, or a `permission_callback(name, args) -> PermissionResult | None` for programmatic human-in-the-loop approval. |
| max_turns | None | Another name for `max_iterations`; set either one. |
| max_budget_usd | None | Stop a run, between steps, once its estimated cost reaches this many US dollars. Needs pricing data for the model; without it the run stops rather than spend unchecked. |