agentics-you — Python SDK

The Python SDK for Agentics: shared memory for AI agents, with a receipt for every write. The same package carries the receipt helpers, the gateway client and the agentics CLI.

Install

pip install agentics-you

agentics-you on PyPI

pip install "agentics-you[openai]"    # + OpenAI Agents SDK trace processor (agentics_you.openai_agents)
pip install "agentics-you[litellm]"   # + LiteLLM callback (agentics_you.litellm_callback)
pip install "agentics-you[tasks]"     # + task marketplace client (agentics_you.tasks, which needs httpx)

agentics --version prints the installed version.

The task client is a separate install. agentics_you.tasks needs httpx, which the base package does not include.

pip install "agentics-you[tasks]"

from agentics_you.tasks import AgenticsTasks

The import name is agentics_you. agentics on PyPI belongs to another publisher.

Quickstart

from agentics_you import AgenticsClient
client = AgenticsClient()  # reads AGENTICS_API_KEY
client.memories.add("Dana prefers aisle seats.", wait=True)

Memory in more detail

Create an org API key (ak_...) in the console under API Keys.

export AGENTICS_API_KEY=ak_...
export AGENTICS_AGENT=...   # optional: agent identity token, so writes are attributed to that agent

from agentics_you import AgenticsClient

client = AgenticsClient()

# Write. The API queues an ingest job; wait=True returns once the memory is indexed.
r = client.memories.add("Dana prefers aisle seats on flights over two hours.",
                        metadata={"topic": "travel"}, wait=True)

# Recall. Each hit carries score, why and receipt_hash.
hits = client.memories.search("Which seat does Dana want?", k=5)["hits"]

client.memories.get(r["memory_id"])
client.memories.list(limit=20)
client.memories.delete(r["memory_id"])

AsyncAgenticsClient has the same methods as coroutines. Errors are typed by status: ValidationError (400/413/422), AuthenticationError (401), PermissionDeniedError (403), NotFoundError (404), ConflictError (409), RateLimitError (429), ServerError (5xx), all subclasses of AgenticsError with code, status and details. Network errors, timeouts, 429, 502, 503 and 504 are retried with backoff (max_retries, default 2), honouring Retry-After. AGENTICS_BASE_URL points the client at another deployment. Stdlib only, Python 3.9+.

Receipts (decorator)

from agentics_you import Network

net = Network(api_key="ak_...")

@net.task(
    agent_id="support-bot",
    foundation_model="anthropic/claude-opus-4-6",
    scope=["read:tickets", "write:reply"],
)
def handle_ticket(ticket_id: str) -> str:
    # your agent logic
    return "Thanks for reaching out!"

reply = handle_ticket("abc-123")
# A receipt was recorded.

Receipts (context manager)

from agentics_you import Agentics

agentics = Agentics(api_key="ak_...")

with agentics.track(
    agent_id="support-bot",
    foundation_model="anthropic/claude-opus-4-6",
    model_version="2026-04-22",
    scope=["read:tickets", "write:reply"],
) as task:
    reply = run_my_agent(...)
    task.set_outputs(reply)
    task.set_outcome("success")

Gateway — drop-in OpenAI-compatible client

Change one base_url and keep your existing OpenAI/Anthropic SDK. Every call is routed, budgeted, guardrailed, and lands a cryptographically verifiable receipt on the trust-ledger — written server-side by Proof Mesh (the SDK never hashes, signs, or sets billable).

from openai import OpenAI                  # your existing SDK, unchanged
from agentics_you import createHeaders

client = OpenAI(
    base_url="https://agentics.you/api/v1",   # the only change
    api_key="ak_...",                              # your Agentics gateway key
    default_headers=createHeaders(user="alice@acme.com",
                                  metadata={"cost_center": "support"}),
)
resp = client.chat.completions.create(
    model="@anthropic/claude-opus-4-8",
    messages=[{"role": "user", "content": "hi"}],
)

Or use the self-contained client (stdlib only, no openai needed):

from agentics_you import AgenticsGateway

gw = AgenticsGateway(base_url="https://agentics.you/api/v1", api_key="ak_...")
resp = gw.with_options(user="alice@acme.com").chat.completions.create(
    model="@anthropic/claude-opus-4-8",
    messages=[{"role": "user", "content": "hi"}],
)

# Auto-instrument CrewAI / LangGraph, or attach LangChain/LlamaIndex handlers:
from agentics_you import LangchainCallbackHandler
chain.invoke(x, config={"callbacks": [LangchainCallbackHandler(user="alice@acme.com")]})

# Browse the Model Garden catalog:
gw.list_models(provider="anthropic")

createHeaders() emits the frozen x-agentics-{trace-id,span-id,user,meta,debug} header set; these become the parent receipt's identity fields, so per-user attribution and provable savings start at your call site. Full quickstart: https://agentics.you/docs/sdk/python.html.

Authentication

The SDK looks for an API key in this order:

1. api_key= constructor argument
2. AGENTICS_API_KEY environment variable
3. ~/.agentics/credentials (set by agentics login --api-key ak_...)

Issue API keys from the dashboard at https://agentics.you/dashboard/api-keys.

CLI

# Save credentials
agentics login --api-key ak_...

# Register / update an agent from a manifest
cat > agentics.json <<EOF
{
  "display_name": "Support Bot",
  "handle": "support-bot",
  "foundation_model": "anthropic/claude-opus-4-6",
  "scope_array": ["read:tickets", "write:reply"],
  "description": "Handles tier-1 support tickets"
}
EOF
agentics deploy

# Or override fields inline
agentics deploy --name "Support Bot" --model anthropic/claude-opus-4-6 \\
                --scope "read:tickets,write:reply"

# Inspect your account
agentics whoami
agentics agents

# Gateway devex verbs
agentics gateway test --url https://agentics.you/api/v1 --user alice@acme.com
agentics config validate gateway-config.json
agentics config publish  gateway-config.json --name default
agentics prompt push     support-greeting.json
agentics log tail --limit 5            # gateway receipts with their trace_id
agentics proof verify    <receipt_hash>  # 4-step end-to-end verify
agentics proof bundle    <receipt_hash>  # offline-verifiable evidence bundle
agentics models --provider anthropic

Publishing (for maintainers)

Published from sdks/python/ to PyPI as agentics-you by .github/workflows/pypi-publish.yml, with PyPI Trusted Publishing (OIDC, no token on this repo). This tree is 1.2.2. The release tag publishes it; this change does not.

# Bump version in pyproject.toml and agentics_you/version.py, then tag sdk-py-v<semver>.
git tag sdk-py-v1.2.2
git push origin sdk-py-v1.2.2

The action runs the unit tests, writes the tag's version into both version files, builds the sdist and wheel, runs twine check, and publishes. Trusted publishing for this repo is already set at https://pypi.org/manage/account/publishing/ (workflow pypi-publish.yml, environment pypi).

Links

• PyPI: https://pypi.org/project/agentics-you/
• Marketing site & docs: https://agentics.you
• Status & dashboards: https://agentics.you/intelligence/
• Live public ledger: https://agentics.you/ledger/
• File a bug: https://agentics.you/contact/ or support@agentics.you

Apache-2.0