Metadata-Version: 2.4
Name: niuniu-agentbox
Version: 0.1.5
Summary: Python SDK for AgentBox private agent state and scoped sharing.
Author: AgentBox
License-Expression: MIT
License-File: LICENSE
Keywords: a2a,agent-memory,agentbox,agents,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# AgentBox Python SDK

Python SDK for [AgentBox](https://agentbox.niuniu.dev/) private agent state and
scoped sharing.

Use the public production service at `https://agentbox.niuniu.dev/` for Agent
Card discovery and SDK integration. Discovery and package installation work
without private repository access.

Full SDK API reference: <https://github.com/pengmu/agent-box/blob/main/docs/sdk-reference.md>

## Install

```bash
python3 -m pip install niuniu-agentbox
```

Import the SDK as `agentbox`:

```python
from agentbox import AgentBoxClient
```

## Production Auth

Creating boxes in production requires an OIDC identity token from a provider
configured by AgentBox, such as Google. Pass that identity token as
`identity_token` with the matching `auth_scheme`; when a recipient uses an
AgentBox grant, keep the scoped grant token separate from the identity token.

## First Private Box With Google OIDC

Get a Google ID token for the Google OAuth client configured by AgentBox
production, then keep it outside source code:

```bash
export AGENTBOX_GOOGLE_ID_TOKEN='<google-id-token>'
```

The token must be a Google ID token, not an OAuth access token, and its `aud`
claim must match the Google OAuth client trusted by AgentBox.

```python
import os

from agentbox import discover_agentbox

service = discover_agentbox(base_url="https://agentbox.niuniu.dev")

agentbox = service.create_client(
    identity_token=os.environ["AGENTBOX_GOOGLE_ID_TOKEN"],
    auth_scheme="google",
)

agentbox.register_agent({
    "display_name": "My First Agent",
    "capabilities": ["notes"],
})

created = agentbox.create_box({
    "name": "First private box",
})

box_id = created["data"]["box"]["box_id"]

agentbox.put_item({
    "box_id": box_id,
    "key": "notes/hello",
    "value": "Hello from an identity-bound private box.",
    "expected_version": 0,
})

manifest = agentbox.get_manifest({
    "box_id": box_id,
})

print([item["key"] for item in manifest["data"]["items"]])
```

The box is private to the verified Google identity. To let another identity
read selected resources, create an AgentBox grant and pass that grant as
`grant_token` while the recipient still authenticates with its own Google ID
token.

## Discovery And Workflow

```python
import os

from agentbox import (
    bootstrap_agentbox_agent,
    client_for_grant,
    create_private_box_with_resources,
    create_scoped_read_grant,
)

session = bootstrap_agentbox_agent(
    base_url="https://agentbox.niuniu.dev",
    client={
        "identity_token": os.environ["RESEARCH_OIDC_JWT"],
        "auth_scheme": "google",
    },
    registration={
        "display_name": "Research Agent",
        "capabilities": ["research"],
    },
)

workspace = create_private_box_with_resources(session.client, {
    "name": "Research handoff",
    "items": [
        {
            "key": "research/summary",
            "value": "Only this summary is shared.",
            "expected_version": 0,
        },
        {
            "key": "state/internal",
            "value": "Private notes stay hidden.",
            "expected_version": 0,
        },
    ],
})

grant = create_scoped_read_grant(session.client, {
    "box_id": workspace["box"]["box_id"],
    "subject": "writer-agent",
    "key_prefixes": ["research/"],
    "ttl_seconds": 3600,
})

writer = client_for_grant(
    session.client,
    grant,
    identity_token=os.environ["WRITER_OIDC_JWT"],
    auth_scheme="google",
)

manifest = writer.get_manifest({"box_id": workspace["box"]["box_id"]})
```

## Auth Modes

AgentBox clients authenticate with OIDC identity tokens. Grant clients can carry
the AgentBox scoped grant separately with `grant_token`, or use
`client_for_grant(...)` to derive a least-privilege client from a grant response.
Pass `auth_scheme` for named providers such as `google`.

## API Reference

The SDK exposes discovery helpers, workflow helpers, and client methods for
agents, boxes, items, events, artifacts, grants, and audit records. See the full
reference for method inputs, return shapes, auth overrides, and error handling:
<https://github.com/pengmu/agent-box/blob/main/docs/sdk-reference.md>

## Pilot Network Usage

Native Pilot identity is provided by a Pilot-aware runtime or the AgentBox Pilot
adapter before requests reach AgentBox. SDK application code should keep using
normal box, item, artifact, grant, manifest, and audit methods. Do not set
`auth_scheme="pilot"` or handcraft Pilot authentication headers in agent code;
that path is for the AgentBox adapter/runtime boundary. If a Pilot caller uses
an AgentBox grant, pass it as `grant_token`.

## Methods

```text
health()
discover_agentbox(base_url=... | agent_card_url=...)
bootstrap_agentbox_agent(...)
create_private_box_with_resources(client, data)
create_scoped_read_grant(client, data)
client_for_grant(client, grant, ...)
register_agent(data=None)
get_agent_profile()
create_box(data)
list_boxes()
get_manifest({"box_id": ...})
put_item(data)
get_item(data)
list_items(data)
append_event(data)
list_events(data)
attach_artifact(data)
list_artifacts({"box_id": ...})
get_artifact(data)
create_grant(data)
list_grants({"box_id": ...})
revoke_grant(data)
with_auth(identity_token=None, grant_token=None, auth_scheme=None)
```

Non-2xx responses and AgentBox `{ "ok": false }` responses raise
`AgentBoxApiError`.

## License

MIT
