SDK for TypeScript and Python
Last updated
Build on the Tempr agent from your own code. The SDKs start tempr acp for you and talk to it over the Agent Client Protocol, so a script gets the same agent the CLI runs: your models, settings, rules, hooks and MCP servers, with its tools running on your machine.
Install
# TypeScript (Node 18 or later); brings the CLI with it
npm install @tempr/sdkThe Python SDK (tempr-sdk, Python 3.10 or later) is coming to PyPI soon; the Python examples on this page show its API as it will ship.
Sign in once, as for the CLI: tempr auth, or set TEMPR_LICENSE_KEY in CI. The TypeScript SDK uses the CLI that @tempr/cli installed; the Python SDK finds tempr on your PATH (install it any way from the CLI page). Either takes a path to another one.
One prompt
query runs a prompt start to finish and yields what happens: the reply as it streams, tool calls, the plan, usage, and last a result with the whole reply, why it stopped, what it cost, and the session's id.
import { query } from "@tempr/sdk";
for await (const event of query({ prompt: "What does this repository do?" })) {
if (event.type === "text") process.stdout.write(event.text);
if (event.type === "result") console.log(`\n(${event.stopReason}, $${event.costUsd ?? 0})`);
}import asyncio
from tempr_sdk import query
async def main():
async for event in query("What does this repository do?"):
if event["type"] == "text":
print(event["text"], end="")
asyncio.run(main())Options
| TypeScript | Python | What it does |
|---|---|---|
cwd | cwd | The folder the agent works in. Default: the current one. |
model | model | A model id from tempr models. Default: yours. |
approvalMode | approval_mode | interactive, bypass (edits without asking) or autopilot. Default: yours. |
canUseTool | can_use_tool | Answers what the agent asks to do: allow, allow_always (calls like it, for the session) or deny. Without it, anything that asks is denied, so set approvalMode for runs nobody watches. |
persona | persona | Every turn runs as this persona, built-in or your own. |
maxTurns | max_turns | The most model calls one prompt's run may make, as --max-turns. |
maxCostUsd | max_cost_usd | The most one prompt's run may spend; the server stops it there, as --max-cost. |
mcpServers | mcp_servers | More MCP servers for the session, in ACP's shape: a command, or an HTTP address. |
tools | tools | Tools that run in your own process (see below). |
resume | resume | A saved session's id: carry on from there. |
pathToTempr | path_to_tempr | The tempr to run. Also TEMPR_PATH. |
A session of several prompts
TemprClient keeps one session open: each prompt continues the conversation, and you can change the mode or model between them, or cancel a running prompt.
import { TemprClient } from "@tempr/sdk";
const client = await TemprClient.start({
approvalMode: "bypass",
canUseTool: async (request) => (request.kind === "execute" ? { behavior: "deny" } : { behavior: "allow" }),
});
try {
for await (const e of client.prompt("Add a test for parsePrice()")) { /* ... */ }
for await (const e of client.prompt("Now run the tests and fix what fails")) { /* ... */ }
} finally {
await client.close(); // the session stays saved: resume it with its id
}Your own tools
A tool defined in your code is offered to the agent beside its own. The SDK serves it to the session as an MCP server on 127.0.0.1, behind a token made for the session; the agent sees it as {server}__{tool} and asks before calling it, like any MCP tool.
import { query, tool, createMcpServer } from "@tempr/sdk";
const lookup = tool("order", "Look up an order by id", { properties: { id: { type: "string" } }, required: ["id"] },
async ({ id }) => JSON.stringify(await orders.get(id)));
for await (const e of query({
prompt: "Why was order 1042 refunded?",
options: { tools: [createMcpServer({ name: "shop", tools: [lookup] })], canUseTool: () => ({ behavior: "allow" }) },
})) { /* ... */ }from tempr_sdk import TemprOptions, create_mcp_server, query, tool
@tool("order", "Look up an order by id", {"properties": {"id": {"type": "string"}}, "required": ["id"]})
async def order(args):
return json.dumps(await orders.get(args["id"]))
options = TemprOptions(tools=[create_mcp_server("shop", [order])], can_use_tool=lambda request: "allow")How it works
The SDKs are thin: they start tempr acp and speak the Agent Client Protocol to it, the same protocol editors such as Zed use. Nothing else needs installing, and they have no dependencies of their own. Options ACP has no field for (the persona and the caps) go to Tempr under _meta.tempr in session/new. Sessions are saved as the CLI saves them, so tempr history lists them too.
The SDK's names follow Claude's Agent SDK where the idea is the same (query, canUseTool, tool), but it isn't a drop-in replacement for it: the protocol underneath is ACP, and the agent is Tempr's, with any model you've set up.
Next steps
- Scripts, pipes & CI: the CLI on its own in scripts.
- Config & troubleshooting: the settings, rules and hooks a session uses.
- MCP servers: servers every session gets.