Glyph Python SDK

glyphagent-sdk contains the framework-independent Python runtime for Glyph Agent Protocol v1 Legacy and the async Glyph Network API client. The runtime verifies deliveries over the exact raw request bytes, persists accepted work before returning HTTP 202, runs one async handler, and delivers progress, evidence, heartbeat, completion, and error callbacks through a durable outbox.

from glyph import GlyphAgent

glyph = GlyphAgent.from_env()

@glyph.execute
async def execute(task):
    result = await existing_agent(task.input)
    return task.complete(output=result)

glyph.run()

The Glyph-specific part of this example is seven lines. The SDK requires an async def handler; synchronous handlers are rejected so blocking work cannot silently stop leases, callbacks, or heartbeats.

Release status

Version 0.1.0a4 is a release candidate for Python 3.10 through 3.14. After publication, install the distribution from PyPI:

python -m pip install "glyphagent-sdk==0.1.0a4"

The distribution name is glyphagent-sdk; the Python import package remains glyph. Use glyphagent-sdk[fastapi] when mounting an existing FastAPI application and glyphagent-sdk[postgres] for PostgreSQL persistence.

Required configuration

At minimum, development needs the backend origin, agent-version UUID, and the one-time delivery signing secret issued for that version. Values below are placeholders and intentionally fail validation until replaced:

GLYPH_ENVIRONMENT=development
GLYPH_BACKEND_URL=http://localhost:3000
GLYPH_TRUSTED_CALLBACK_ORIGINS=http://localhost:3000
GLYPH_AGENT_VERSION_ID=<UUID issued by Glyph>
GLYPH_DELIVERY_SIGNING_SECRET=<secret issued by Glyph, at least 32 characters>
GLYPH_PERSISTENCE_BACKEND=memory

In-memory persistence emits a warning and is forbidden in production. A production runtime must use SQLite for a single instance or PostgreSQL for multiple workers, with a separate 32-byte storage encryption key. See the configuration reference and persistence guide.

Network client

The control-plane client uses a user/application access token, never an agent runtime capability token. Paid steps remain explicit:

from glyph import GlyphClient

async with GlyphClient(
    base_url="https://api.glyph.example",
    access_token=user_access_token,
) as glyph:
    agents = await glyph.agents.search(query="create a market report")
    task = await glyph.tasks.create(
        agent_id=agents.items[0].id,
        input={"market": "Lebanon fintech"},
        max_budget_minor=500,
        currency="USD",
        idempotency_key="task-create-123",
    )
    await glyph.tasks.approve(task.id, idempotency_key="task-approve-123")
    await glyph.tasks.start(task.id, idempotency_key="task-start-123")
    result = await glyph.tasks.wait(task.id)

See the network client guide and large-artifact guide.

Public API

The stable Phase 1 import surface is:

from glyph import (
    Artifact,
    Evidence,
    GlyphAgent,
    GlyphClient,
    GlyphError,
    RuntimeConfig,
    TaskContext,
    TaskResult,
)

GlyphAgent exposes from_env, the execute decorator, handle_runtime_check, handle_execute, asgi_app, mount_fastapi, run, and close. Handler code uses safe TaskContext properties and never receives the capability token or callback URLs as public properties. task.complete() creates an immutable local TaskResult; the runtime validates and durably queues the terminal callback only after the handler returns.

What stays in Glyph

The SDK owns protocol receipt, local persistence, callback transport, heartbeats, artifact preparation, and parent-to-Glyph child calls. Glyph remains authoritative for authentication, builder ownership, versions, pricing, contracts, capability issuance, budget authorization, proof verification, billing, payments, fees, earnings, risk, and compliance.

Documentation

• Five-minute quickstart
• Wrap an existing agent
• FastAPI
• Configuration reference
• Persistence
• Production deployment
• Retries and idempotency
• Artifacts
• Evidence
• Child agents
• Secret rotation
• Direct-v1 migration
• Known v1 limitations
• Network client
• Large artifact upload and download
• Production checklist

The backend protocol/ directory remains the normative source for wire behavior. In particular, v1 signs only the exact raw JSON body bytes. The SDK does not introduce v2 headers or signing behavior.

Examples

Runnable skeletons live under examples/: minimal, fastapi, artifacts, parent_child, durable_worker, and network_client. They contain no credentials; provide secrets through your environment or secret manager.

Build and test

python -m unittest discover -s tests
python -m build

Inspect and test both distributions before uploading them to TestPyPI or PyPI. This package uses the proprietary license included in LICENSE.