niuniu-agentbox 0.1.1

Python SDK for AgentBox private agent state and scoped sharing.

AgentBox Python SDK

Python SDK for AgentBox private agent state and scoped sharing.

Install

python3 -m pip install niuniu-agentbox

Import the SDK as agentbox:

from agentbox import AgentBoxClient

Discovery And Workflow

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"]})

Admin Token Auth

For local development or operator-controlled scripts, use an actor label and an AgentBox admin token:

from agentbox import AgentBoxClient

client = AgentBoxClient(
    base_url="http://127.0.0.1:3000",
    actor="research-agent",
    token="dev-token",
)

Auth Modes

AgentBox supports admin/grant-token compatibility auth with actor + token, and OIDC auth with identity_token. Pass auth_scheme for named providers such as google.

Methods

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()
list_agents(admin=True)
update_agent_status({"identity_key": ..., "status": "blocked"}, admin=True)
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)
list_audit({"box_id": ...})
with_auth(actor=None, token=None, identity_token=None, grant_token=None, auth_scheme=None)

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

License

MIT