Features · Build · Tools

Any Python function is a tool.

Name: SHIPIT Agent
Author: SHIPIT

A tool is a name, a description, a JSON Schema for its arguments and a function that runs. There are three ways to write one; all three work with every model.

Custom tools Tools catalog

tools.pylive

from shipit_agent import Agentfrom shipit_agent.llms import build_llm_from_envfrom shipit_agent.tools import FunctionTooldef find_customer(email: str) -> str:    """Look up a customer by email and return their plan and signup date."""    return f"{email}: Pro plan since 2025-03-14"

$ pythonexample output

running…

How it works

Your function

docstring and type hints

FunctionTool

builds the schema

Model

decides to call it

Result

back into the loop

See it run

The code is a checked example from the docs; the output is an example of what it prints.

tools.py

from shipit_agent import Agent
from shipit_agent.llms import build_llm_from_env
from shipit_agent.tools import FunctionTool


def find_customer(email: str) -> str:
    """Look up a customer by email and return their plan and signup date."""
    return f"{email}: Pro plan since 2025-03-14"


agent = Agent(
    llm=build_llm_from_env(),
    tools=[FunctionTool.from_callable(find_customer, read_only=True)],
)

$ pythonexample output

running…

Go deeper

6 more ways to use it

Each example is from the docs and checked against the library.

From a function

Read in the docs

The simplest. The function's name, docstring and type hints become the tool.

example.py

from shipit_agent import Agent
from shipit_agent.llms import build_llm_from_env
from shipit_agent.tools import FunctionTool


def find_customer(email: str) -> str:
    """Look up a customer by email and return their plan and signup date."""
    return f"{email}: Pro plan since 2025-03-14"


agent = Agent(
    llm=build_llm_from_env(),
    tools=[FunctionTool.from_callable(find_customer, read_only=True)],
)

Catalog

All 66 built-in tools

Everything Agent.with_builtins() can attach. Read-only tools run without asking; the rest pass the permission gate first.

66 of 66 tools

read_fileread-only
Read a file from the local project. Text files return line-numbered content; Word/Excel/PowerPoint/HTML/CSV documents are extracted to clean Markdown; images and PDFs return as viewable media.
Files and code
write_filechanges things
Create or overwrite a file in the local project.
Files and code
edit_filechanges things
Apply an exact string replacement patch to an existing file.
Files and code
multi_editchanges things
Apply several exact string-replacement edits to ONE file atomically. Edits apply in order to the same file; if any old_text is missing or ambiguous, nothing is written.
Files and code
notebook_editchanges things
Read, edit, add, or delete cells in a Jupyter notebook (.ipynb).
Files and code
glob_filesread-only
Find files in the local project by glob pattern.
Files and code
grep_filesread-only
Search file contents in the local project using ripgrep when available.
Files and code
bashchanges things
Run a shell command in the project root: tests, builds, git, package managers, scripts. Risky commands (deleting, publishing, writing outside the project) need approval.
Files and code
bash_jobchanges things
Read output from, or kill, a background command started by the bash tool. Pass the job_id the bash tool returned.
Files and code
run_codechanges things
Execute Python or shell code in a local subprocess workspace.
Files and code
git_opschanges things
Structured git operations: status, diff, log, show, blame, branch, add, commit, checkout, stash (push/reset are disabled by default).
Files and code
workspace_filesread-only
Read, write, list, and inspect files in the local shipit workspace.
Files and code
download_filechanges things
Download a file (binary-safe: zip, csv, image, pdf, …) from an http(s) URL to local disk.
Files and code
present_filechanges things
Present a file you created or have (image, audio, video, PDF, document, spreadsheet, data) to the user as a downloadable, previewable deliverable. Use after you generate or save a file the user should receive — pass the path. This does not create the file; the file must already exist.
Files and code
pdfread-only
Extract text, per-page content, or metadata from a PDF file (local or URL).
Files and code
web_searchread-only
Search the web and return structured search results.
The web
open_urlread-only
Fetch a URL and return a clean text excerpt.
The web
playwright_browsechanges things
Use Playwright to open a page and return the rendered text content.
The web
deep_researchread-only
Deep multi-angle research: several search queries, deduped sources, top pages fetched — returns a structured digest with citations.
The web
todochanges things
Maintain a live, replace-on-write checklist of tasks for a multi-step job so progress is observable. Pass the full updated list each call; mark exactly one item in_progress and flip items to completed as you finish them.
Planning and checking
plan_taskread-only
Generate a concrete execution plan with ordered steps, risks, and checkpoints.
Planning and checking
present_planread-only
Submit your plan for approval and stop. Call this once, in plan mode, when you have finished researching and are ready to act — the plan is shown to the user, who approves it (letting you execute) or asks for changes. Do not act before it is approved.
Planning and checking
decompose_problemread-only
Break a problem into workstreams, assumptions, risks, evidence needs, and next actions.
Planning and checking
decision_matrixread-only
Compare options against explicit criteria and recommend the strongest choice.
Planning and checking
synthesize_evidenceread-only
Turn raw observations into facts, inferences, gaps, and recommendations.
Planning and checking
verify_outputread-only
Check whether content satisfies a set of required criteria.
Planning and checking
build_promptread-only
Build or refine a system prompt from goals, constraints, and style instructions.
Planning and checking
give_upread-only
Declare that you cannot complete the task, with a specific reason. Use only when genuinely blocked, not when the work is merely hard.
Planning and checking
ask_userread-only
Request structured user input as part of a human-in-the-loop flow.
People
ask_user_asyncread-only
Pause an Autopilot run to ask the user a clarifying question — non-blocking; the run halts into awaiting_user and resumes once the user answers via `shipit answer <run_id> "..."`.
People
human_reviewread-only
Pause for human review and approval before continuing.
People
sub_agentchanges things
Delegate a focused task to a sub-agent with its own context and tools. Use for searches that would flood your context, or for independent work you can run in parallel.
Agents and tools
task_stopchanges things
Stop a background task (a command or a sub-agent) by its task id.
Agents and tools
tool_searchread-only
Search the current agent's available tools and return a ranked shortlist of the best matches for a task. Use this when many tools are available and no loaded tool fits. Call an already loaded matching tool directly instead of searching again.
Agents and tools
memorychanges things
Store and retrieve structured memory facts for the current agent.
Memory
visionread-only
Send an image (file path, URL, data URL, or base64) to a vision-capable LLM and return a textual analysis.
Media
image_generatechanges things
Generate an image from a text description. Returns the image so you can see it and the user can view it. Use for illustrations, diagrams, mockups, icons — not for editing an existing file.
Media
text_to_speechchanges things
Convert text to spoken audio. Saves an audio file and returns its path so a chat surface can play it. Use for a spoken summary or voice reply.
Media
video_generatechanges things
Generate a short video clip from a text description. Saves an MP4 and returns its path so a chat surface can play it. Use for b-roll, product shots, animations, concept scenes — not for editing existing footage.
Media
build_artifactchanges things
Create a deliverable (report, page, code, diagram, data) with a stable id, then update or rewrite it; every change is saved as a new version.
Documents and apps
build_documentchanges things
Create a polished PDF report, Excel workbook, Word document, PowerPoint deck, or styled HTML page from structured content.
Documents and apps
render_dashboardchanges things
Render a rich HTML dashboard (metrics, timeline, bars, cards, phases, chart, verdict) from a structured spec.
Documents and apps
create_appchanges things
Create an app: a small program saved in the workspace that can be run again later with use_app. Start from a blueprint or supply app.py.
Documents and apps
use_appchanges things
Run an app with input and get its result. Use this instead of redoing work the app already encodes.
Documents and apps
list_blueprintsread-only
List the app blueprints available to start a new app from.
Documents and apps
set_app_bindingchanges things
Wire one of your resource bindings into an app, so the app can use it. An app only ever sees what you wire into it.
Documents and apps
describe_bindingread-only
Return the methods and parameters of one binding in `env`. Call this before using a binding for the first time.
Documents and apps
githubchanges things
Work with GitHub issues, pull requests, file contents, and Actions workflow runs via the REST API.
Services
gitlabchanges things
Search GitLab issues, manage merge requests, read files, and control CI pipelines.
Services
jirachanges things
Search Jira issues and create Jira issues.
Services
linearchanges things
Search Linear issues and create Linear issues.
Services
notionchanges things
Search Notion pages and create Notion pages.
Services
confluencechanges things
Search and create Confluence pages.
Services
slackchanges things
Search Slack messages and post Slack messages.
Services
gmail_searchread-only
Search, read, draft, and send Gmail messages from a configured Google account.
Services
google_calendarchanges things
Search and list Google Calendar events.
Services
google_drivechanges things
Search and list Google Drive files.
Services
google_sheetschanges things
Read / write Google Sheets cells, ranges, formulas, and sheet structure.
Services
figmachanges things
Read Figma files, render node images, browse and post comments, and introspect team projects / components via the Figma REST API.
Services
salesforcechanges things
Search Salesforce records; query SOQL/SOSL; read accounts/opportunities/contacts; log activities.
Services
stripechanges things
Read-heavy Stripe data: customers, charges, subscriptions, invoices, products. Writes gated by allow_writes.
Services
zendeskchanges things
Search / read / comment on Zendesk tickets and users; list and preview macros.
Services
linkedin_searchread-only
Read-only LinkedIn lookup: profiles, companies, employee search. NO messaging, connection requests, or automation — this tool is intentionally read-only to keep agents compliant with LinkedIn ToS.
Services
sqlchanges things
Query a SQL database. Reads by default; set allow_writes=True to enable mutations.
Services
custom_apichanges things
Call a configured custom HTTP API.
Services
connectionsread-only
List which external services are connected and which need authenticating, or request a connection you need.
Services

What you get

From a function
The name, docstring and type hints become the tool.
As a class
A class with a schema and run() when you need more control.
Results and errors
Return text or rich output; a raised error goes back to the model to recover from.
66 built in
Agent.with_builtins() attaches files, shell, web, planning, documents and more.

Agent parameters

Parameter	Default	What it does
tools	empty	The tools the agent may call.
deferred_tools	'auto'	Default "auto": above ten tools, keep nine core capabilities and a discovery tool. discovery_priority on a tool overrides core ranking; ties follow registration order.
parallel_tool_execution	True	Run a response's tool calls concurrently when every one is read-only. Writes and unknown tools always run one at a time, in order.
max_tool_concurrency	None	None means no cap; otherwise bound concurrent local tool calls per turn.
heal_tool_calls	True	Promote tool calls that small models emit as TEXT (<tool_call> tags, fenced JSON, bare call-shaped JSON) into structured calls. Response- side only; only declared tool names qualify.
max_tool_output_chars	16000	Bound only the model-visible copy; AgentResult keeps complete tool output. Capped by default: a message list is cumulative, so one 138,000-character tool result is not paid once — it is re-sent on every turn that follows it.

More in Build

Next: Structured output

from shipit_agent import Agentfrom shipit_agent.llms import build_llm_from_envfrom shipit_agent.tools import FunctionTooldef find_customer(email: str) -> str: """Look up a customer by email and return their plan and signup date.""" return f"{email}: Pro plan since 2025-03-14"

See it run

The code is a checked example from the docs; the output is an example of what it prints.

tools.py

from shipit_agent import Agent
from shipit_agent.llms import build_llm_from_env
from shipit_agent.tools import FunctionTool


def find_customer(email: str) -> str:
    """Look up a customer by email and return their plan and signup date."""
    return f"{email}: Pro plan since 2025-03-14"


agent = Agent(
    llm=build_llm_from_env(),
    tools=[FunctionTool.from_callable(find_customer, read_only=True)],
)

$ pythonexample output

running…

Go deeper

6 more ways to use it

Each example is from the docs and checked against the library.

From a function

Read in the docs

The simplest. The function's name, docstring and type hints become the tool.

example.py

from shipit_agent import Agent
from shipit_agent.llms import build_llm_from_env
from shipit_agent.tools import FunctionTool


def find_customer(email: str) -> str:
    """Look up a customer by email and return their plan and signup date."""
    return f"{email}: Pro plan since 2025-03-14"


agent = Agent(
    llm=build_llm_from_env(),
    tools=[FunctionTool.from_callable(find_customer, read_only=True)],
)

Catalog

All 66 built-in tools

Everything Agent.with_builtins() can attach. Read-only tools run without asking; the rest pass the permission gate first.

66 of 66 tools

read_fileread-only
Read a file from the local project. Text files return line-numbered content; Word/Excel/PowerPoint/HTML/CSV documents are extracted to clean Markdown; images and PDFs return as viewable media.
Files and code
write_filechanges things
Create or overwrite a file in the local project.
Files and code
edit_filechanges things
Apply an exact string replacement patch to an existing file.
Files and code
multi_editchanges things
Apply several exact string-replacement edits to ONE file atomically. Edits apply in order to the same file; if any old_text is missing or ambiguous, nothing is written.
Files and code
notebook_editchanges things
Read, edit, add, or delete cells in a Jupyter notebook (.ipynb).
Files and code
glob_filesread-only
Find files in the local project by glob pattern.
Files and code
grep_filesread-only
Search file contents in the local project using ripgrep when available.
Files and code
bashchanges things
Run a shell command in the project root: tests, builds, git, package managers, scripts. Risky commands (deleting, publishing, writing outside the project) need approval.
Files and code
bash_jobchanges things
Read output from, or kill, a background command started by the bash tool. Pass the job_id the bash tool returned.
Files and code
run_codechanges things
Execute Python or shell code in a local subprocess workspace.
Files and code
git_opschanges things
Structured git operations: status, diff, log, show, blame, branch, add, commit, checkout, stash (push/reset are disabled by default).
Files and code
workspace_filesread-only
Read, write, list, and inspect files in the local shipit workspace.
Files and code
download_filechanges things
Download a file (binary-safe: zip, csv, image, pdf, …) from an http(s) URL to local disk.
Files and code
present_filechanges things
Present a file you created or have (image, audio, video, PDF, document, spreadsheet, data) to the user as a downloadable, previewable deliverable. Use after you generate or save a file the user should receive — pass the path. This does not create the file; the file must already exist.
Files and code
pdfread-only
Extract text, per-page content, or metadata from a PDF file (local or URL).
Files and code
web_searchread-only
Search the web and return structured search results.
The web
open_urlread-only
Fetch a URL and return a clean text excerpt.
The web
playwright_browsechanges things
Use Playwright to open a page and return the rendered text content.
The web
deep_researchread-only
Deep multi-angle research: several search queries, deduped sources, top pages fetched — returns a structured digest with citations.
The web
todochanges things
Maintain a live, replace-on-write checklist of tasks for a multi-step job so progress is observable. Pass the full updated list each call; mark exactly one item in_progress and flip items to completed as you finish them.
Planning and checking
plan_taskread-only
Generate a concrete execution plan with ordered steps, risks, and checkpoints.
Planning and checking
present_planread-only
Submit your plan for approval and stop. Call this once, in plan mode, when you have finished researching and are ready to act — the plan is shown to the user, who approves it (letting you execute) or asks for changes. Do not act before it is approved.
Planning and checking
decompose_problemread-only
Break a problem into workstreams, assumptions, risks, evidence needs, and next actions.
Planning and checking
decision_matrixread-only
Compare options against explicit criteria and recommend the strongest choice.
Planning and checking
synthesize_evidenceread-only
Turn raw observations into facts, inferences, gaps, and recommendations.
Planning and checking
verify_outputread-only
Check whether content satisfies a set of required criteria.
Planning and checking
build_promptread-only
Build or refine a system prompt from goals, constraints, and style instructions.
Planning and checking
give_upread-only
Declare that you cannot complete the task, with a specific reason. Use only when genuinely blocked, not when the work is merely hard.
Planning and checking
ask_userread-only
Request structured user input as part of a human-in-the-loop flow.
People
ask_user_asyncread-only
Pause an Autopilot run to ask the user a clarifying question — non-blocking; the run halts into awaiting_user and resumes once the user answers via `shipit answer <run_id> "..."`.
People
human_reviewread-only
Pause for human review and approval before continuing.
People
sub_agentchanges things
Delegate a focused task to a sub-agent with its own context and tools. Use for searches that would flood your context, or for independent work you can run in parallel.
Agents and tools
task_stopchanges things
Stop a background task (a command or a sub-agent) by its task id.
Agents and tools
tool_searchread-only
Search the current agent's available tools and return a ranked shortlist of the best matches for a task. Use this when many tools are available and no loaded tool fits. Call an already loaded matching tool directly instead of searching again.
Agents and tools
memorychanges things
Store and retrieve structured memory facts for the current agent.
Memory
visionread-only
Send an image (file path, URL, data URL, or base64) to a vision-capable LLM and return a textual analysis.
Media
image_generatechanges things
Generate an image from a text description. Returns the image so you can see it and the user can view it. Use for illustrations, diagrams, mockups, icons — not for editing an existing file.
Media
text_to_speechchanges things
Convert text to spoken audio. Saves an audio file and returns its path so a chat surface can play it. Use for a spoken summary or voice reply.
Media
video_generatechanges things
Generate a short video clip from a text description. Saves an MP4 and returns its path so a chat surface can play it. Use for b-roll, product shots, animations, concept scenes — not for editing existing footage.
Media
build_artifactchanges things
Create a deliverable (report, page, code, diagram, data) with a stable id, then update or rewrite it; every change is saved as a new version.
Documents and apps
build_documentchanges things
Create a polished PDF report, Excel workbook, Word document, PowerPoint deck, or styled HTML page from structured content.
Documents and apps
render_dashboardchanges things
Render a rich HTML dashboard (metrics, timeline, bars, cards, phases, chart, verdict) from a structured spec.
Documents and apps
create_appchanges things
Create an app: a small program saved in the workspace that can be run again later with use_app. Start from a blueprint or supply app.py.
Documents and apps
use_appchanges things
Run an app with input and get its result. Use this instead of redoing work the app already encodes.
Documents and apps
list_blueprintsread-only
List the app blueprints available to start a new app from.
Documents and apps
set_app_bindingchanges things
Wire one of your resource bindings into an app, so the app can use it. An app only ever sees what you wire into it.
Documents and apps
describe_bindingread-only
Return the methods and parameters of one binding in `env`. Call this before using a binding for the first time.
Documents and apps
githubchanges things
Work with GitHub issues, pull requests, file contents, and Actions workflow runs via the REST API.
Services
gitlabchanges things
Search GitLab issues, manage merge requests, read files, and control CI pipelines.
Services
jirachanges things
Search Jira issues and create Jira issues.
Services
linearchanges things
Search Linear issues and create Linear issues.
Services
notionchanges things
Search Notion pages and create Notion pages.
Services
confluencechanges things
Search and create Confluence pages.
Services
slackchanges things
Search Slack messages and post Slack messages.
Services
gmail_searchread-only
Search, read, draft, and send Gmail messages from a configured Google account.
Services
google_calendarchanges things
Search and list Google Calendar events.
Services
google_drivechanges things
Search and list Google Drive files.
Services
google_sheetschanges things
Read / write Google Sheets cells, ranges, formulas, and sheet structure.
Services
figmachanges things
Read Figma files, render node images, browse and post comments, and introspect team projects / components via the Figma REST API.
Services
salesforcechanges things
Search Salesforce records; query SOQL/SOSL; read accounts/opportunities/contacts; log activities.
Services
stripechanges things
Read-heavy Stripe data: customers, charges, subscriptions, invoices, products. Writes gated by allow_writes.
Services
zendeskchanges things
Search / read / comment on Zendesk tickets and users; list and preview macros.
Services
linkedin_searchread-only
Read-only LinkedIn lookup: profiles, companies, employee search. NO messaging, connection requests, or automation — this tool is intentionally read-only to keep agents compliant with LinkedIn ToS.
Services
sqlchanges things
Query a SQL database. Reads by default; set allow_writes=True to enable mutations.
Services
custom_apichanges things
Call a configured custom HTTP API.
Services
connectionsread-only
List which external services are connected and which need authenticating, or request a connection you need.
Services

What you get

From a function

The name, docstring and type hints become the tool.

As a class

A class with a schema and run() when you need more control.

Results and errors

Return text or rich output; a raised error goes back to the model to recover from.

66 built in

Agent.with_builtins() attaches files, shell, web, planning, documents and more.

Agent parameters

Parameter	Default	What it does
tools	empty	The tools the agent may call.
deferred_tools	'auto'	Default "auto": above ten tools, keep nine core capabilities and a discovery tool. discovery_priority on a tool overrides core ranking; ties follow registration order.
parallel_tool_execution	True	Run a response's tool calls concurrently when every one is read-only. Writes and unknown tools always run one at a time, in order.
max_tool_concurrency	None	None means no cap; otherwise bound concurrent local tool calls per turn.
heal_tool_calls	True	Promote tool calls that small models emit as TEXT (<tool_call> tags, fenced JSON, bare call-shaped JSON) into structured calls. Response- side only; only declared tool names qualify.
max_tool_output_chars	16000	Bound only the model-visible copy; AgentResult keeps complete tool output. Capped by default: a message list is cumulative, so one 138,000-character tool result is not paid once — it is re-sent on every turn that follows it.