mycode-sdk
Lightweight Python SDK for building AI agents. Multi-turn conversations, tool calling, session persistence, and streaming events. Provider adapters for Anthropic, OpenAI, Google, and more.
Install
uv add mycode-sdk
# or
pip install mycode-sdk
Quick start
import asyncio
from pathlib import Path
from mycode import Agent, tool
@tool
def read_file(path: str) -> str:
"""Read a UTF-8 text file.
Args:
path: File path, relative to the working directory.
"""
return Path(path).read_text(encoding="utf-8")
async def main() -> None:
agent = Agent(
model="claude-sonnet-5",
api_key="YOUR_API_KEY",
tools=[read_file],
)
async for event in agent.achat("Read pyproject.toml and tell me the project name."):
if event.type == "text":
print(event.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 synchronous call, use run():
result = agent.run("Read pyproject.toml and tell me the project name.")
print(result.text)
Providers
The SDK infers the provider from the model string (claude-* to Anthropic, gpt-* to OpenAI, etc.). API keys are auto-discovered from environment variables:
| Provider | id | Env var |
|---|---|---|
| Anthropic | anthropic |
ANTHROPIC_API_KEY |
| OpenAI | openai |
OPENAI_API_KEY |
| Google Gemini | google |
GEMINI_API_KEY |
| Moonshot | moonshotai |
MOONSHOT_API_KEY |
| MiniMax | minimax |
MINIMAX_API_KEY |
| DeepSeek | deepseek |
DEEPSEEK_API_KEY |
| Z.AI | zai |
ZAI_API_KEY |
| OpenRouter | openrouter |
OPENROUTER_API_KEY |
| Alibaba Cloud | alibaba |
DASHSCOPE_API_KEY |
| xAI | xai |
XAI_API_KEY |
| OpenAI-compatible | openai_chat |
- |
Pass api_key= to override the env var, api_base= for a custom endpoint. Model metadata is bundled from models.dev; pass context_window, supports_image_input, or supports_pdf_input to override.
Call agent.set_model(...) between turns to switch models; the conversation carries over.
Multi-turn conversations
Call achat() or run() again on the same Agent to continue:
agent = Agent(model="claude-sonnet-5", api_key="...")
agent.run("What is 2 + 2?")
agent.run("Now multiply that by 10.") # remembers the earlier answer
agent.clear() drops in-memory history. agent.messages accumulates across calls.
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:
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 without that capability yields an error event. A bad path or unsupported type raises ValueError before the provider 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-5",
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.
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-5",
api_key="...",
tools=[greet],
)
To call another registered tool from inside a tool, type the first parameter as ToolContext and dispatch by name:
from mycode import ToolContext, tool
@tool
def greet_team(ctx: ToolContext, names: list[str]) -> str:
"""Greet several people at once."""
return "\n".join(ctx.call("greet", {"name": name}).output for name in names)
Async tools use await ctx.acall(name, args) instead.
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:
import os
from mycode import Agent, Hooks, ToolExecutionResult, tool
hooks = Hooks()
@tool
def delete_file(path: str) -> str:
"""Delete a file.
Args:
path: Path of the file to delete.
"""
os.remove(path)
return f"deleted {path}"
@hooks.before_tool
async def protect_dotfiles(ctx):
if ctx.tool_name == "delete_file" and str(ctx.tool_input.get("path") or "").startswith("."):
return ToolExecutionResult(output="error: blocked", is_error=True)
return None
agent = Agent(
model="claude-sonnet-5",
api_key="...",
tools=[delete_file],
hooks=hooks,
)
@hooks.after_tool runs after the tool and can replace the result (audit, redact, etc.).
Further reading
See docs/sdk.md for the streaming event API, cancellation, retries, compaction, session internals, and the full Agent / @tool reference.
Metadata
Release files for mycode-sdk 0.22.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mycode_sdk-0.22.0.tar.gz | 60.7 kB | Without provenance | Details for mycode_sdk-0.22.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mycode_sdk-0.22.0-py3-none-any.whl | Python 3 | none | any | Details for mycode_sdk-0.22.0-py3-none-any.whl |
Total release size: 132.2 kB
Release files / mycode_sdk-0.22.0.tar.gz
| Download URL | mycode_sdk-0.22.0.tar.gz |
|---|---|
| Size | 60.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
723435448234d5ad67bc8991e776e21e219c3d911688afd04489564670c49180
|
|
BLAKE2b-256 checksum How to use checksums |
164f99957849ff3a21b95e309c341da56286725f8d6306954c6c1e2d4a7d948f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","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.22.0-py3-none-any.whl
| Download URL | mycode_sdk-0.22.0-py3-none-any.whl |
|---|---|
| Size | 71.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e195233a003ec7e0c0adc3c5ac04666437140020e199389a983fe64904e518a7
|
|
BLAKE2b-256 checksum How to use checksums |
d0ad04651fa6d48311fcaf887022295e40c991d6984d6ce54e46982892cc39bb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for mycode-sdk 0.22.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.