Skip to main content

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)

Source distribution for mycode-sdk 0.22.0
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)

Table of built distributions (wheels) for mycode-sdk 0.22.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.22.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page