mycode-sdk
Lightweight Python SDK for building AI agents.
Install
uv add mycode-sdk
# or
pip install mycode-sdk
Quick start
import asyncio
from mycode import Agent, bash_tool, read_tool
async def main() -> None:
agent = Agent(
model="claude-sonnet-4-6",
api_key="YOUR_API_KEY",
tools=[read_tool, bash_tool],
)
async for event in agent.achat("Read pyproject.toml and tell me the project name."):
if event.type == "text":
print(event.data["delta"], end="", flush=True)
asyncio.run(main())
Agent(...) infers the provider from the model id. No tools are registered unless you pass tools=[...].
For a simple synchronous call, use run():
result = agent.run("Read pyproject.toml and tell me the project name.")
print(result.text)
Multi-turn conversations
Call achat() or run() again on the same Agent to continue the conversation:
agent = Agent(model="claude-sonnet-4-6", api_key="...")
agent.run("What is 2 + 2?")
agent.run("Now multiply that by 10.") # remembers the earlier answer
Attachments
Pass attachments to achat() or run() to add files alongside the prompt:
from mycode import Attachment
agent.run("Describe these.", attachments=["diagram.png", "report.pdf", "notes.txt"])
# Or build them explicitly — raw bytes and inline text never touch the disk:
agent.run(
"Review.",
attachments=[
Attachment.path("diagram.png"),
Attachment.bytes(png_data, media_type="image/png"),
Attachment.text("TODO: ship it", name="note.md"),
],
)
Images support image/png, image/jpeg, image/gif, image/webp; documents support application/pdf. Sending an image or PDF to a model that lacks that capability yields an error event; a bad path or unsupported type raises ValueError before the model is called.
Saving sessions
Pass session_dir to persist the conversation to disk. Each session lives in a subdirectory named by session_id:
from pathlib import Path
agent = Agent(
model="claude-sonnet-4-6",
api_key="...",
session_dir=Path("./chats"),
session_id="my-chat",
)
Construct another Agent with the same (session_dir, session_id) to load the conversation history.
Built-in tools
from mycode import read_tool, write_tool, edit_tool, bash_tool
Four tools for reading, writing, editing files, and running shell commands. Opt in by passing them to tools=[...].
Custom tools
Decorate a typed function with @tool:
from mycode import Agent, tool
@tool
def greet(name: str) -> str:
"""Return a friendly greeting.
Args:
name: Person name.
"""
return f"hello, {name}"
agent = Agent(
model="claude-sonnet-4-6",
api_key="...",
tools=[greet],
)
To call a built-in tool from inside your own tool, type the first parameter as ToolContext:
from mycode import ToolContext, tool
@tool
def summarize_file(ctx: ToolContext, path: str) -> str:
"""Return the first line of a text file."""
result = ctx.read(path)
return result.output.splitlines()[0] if result.output else ""
Async tools use await ctx.aread(), await ctx.awrite(), await ctx.aedit(), and await ctx.abash(). Use await ctx.acall(name, args) to call another registered tool by name.
Tool hooks
Inspect or replace tool calls before they run. Return None from before_tool to let the tool execute, or a ToolExecutionResult to skip it:
from mycode import Agent, Hooks, ToolExecutionResult, bash_tool
hooks = Hooks()
@hooks.before_tool
async def block_rm(ctx):
cmd = str(ctx.tool_input.get("command") or "")
if ctx.tool_name == "bash" and "rm -rf" in cmd:
return ToolExecutionResult(output="error: blocked", is_error=True)
return None
agent = Agent(
model="claude-sonnet-4-6",
api_key="...",
tools=[bash_tool],
hooks=hooks,
)
@hooks.after_tool runs after the tool and can replace the result (audit, redact, etc.).
See docs/sdk.md for the event stream, cancellation, sessions, and the full Agent / @tool reference.
1 maintainer
Release files for mycode-sdk 0.11.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| mycode_sdk-0.11.1.tar.gz | 53.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| mycode_sdk-0.11.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 115.1 kB
Release files / mycode_sdk-0.11.1.tar.gz
| Download URL | mycode_sdk-0.11.1.tar.gz |
|---|---|
| Size | 53.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
530118f52ef4be0cbc7868932eeaf6680d6fbffa6578404abce9f538b5f10916
|
|
BLAKE2b-256 checksum How to use checksums |
81f87812285b5f28ee64d43da9ad54e2057b4d28c4358caa7ce2810d5d2c9a8a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.30 {"installer":{"name":"uv","version":"0.11.30","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / mycode_sdk-0.11.1-py3-none-any.whl
| Download URL | mycode_sdk-0.11.1-py3-none-any.whl |
|---|---|
| Size | 62.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
de982d5b85f328734c2c9d5da03f37588e3bcf4dc9f8c25b06d9688ccfddc237
|
|
BLAKE2b-256 checksum How to use checksums |
2cd3cb9282a26ccc7c8a6eedbcee59d147c2cdcaa17dd5b02d3405a0b1d592c8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.30 {"installer":{"name":"uv","version":"0.11.30","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
