feat: Add `register_agent()` for programmatic agent registration

[beonde]

Summary

Add a register_agent() function to the SDK that allows agents to self-register with the CapiscIO registry programmatically, eliminating the need to manually register via the web UI.

Motivation

Currently, production mode requires:

1. Log into registry.capisc.io
2. Manually create an agent
3. Copy the agent UUID
4. Set environment variables

This friction hurts developer experience, especially for:

• CI/CD pipelines that spin up agents dynamically
• Multi-agent systems that need to register agents programmatically
• Dev/test environments that want to quickly register ephemeral agents

Proposed API

from capiscio import register_agent

# Register a new agent and get back credentials
agent_id = await register_agent(
    api_key="capiscio_...",
    agent_name="my-crewai-agent",
    description="A CrewAI agent for data analysis",
    capabilities=["data-analysis", "reporting"],
    tags=["crewai", "analytics"],
    registry_url="https://registry.capisc.io"  # optional, has default
)

# Then use it with SimpleGuard/BadgeKeeper
guard = SimpleGuard(agent_id=agent_id)

Implementation Notes

• Server endpoint already exists: POST /v1/sdk/agents in capiscio-server
• Auth: Requires X-Capiscio-Registry-Key header (API key)
• gRPC stub exists in capiscio-core but is not implemented (returns "not yet implemented")

Request format (from server tests):

POST /v1/sdk/agents
Headers:
  X-Capiscio-Registry-Key: <api_key>
Body:
  {
    "name": "agent-name",
    "description": "...",
    "capabilities": [...],
    "tags": [...]
  }

Response:

{
  "id": "uuid-of-created-agent",
  "did": "did:key:...",
  ...
}

Tasks

• Add register_agent() async function to SDK
• Add sync wrapper register_agent_sync()
• Handle error cases (duplicate name, invalid API key, rate limits)
• Add to SDK documentation
• Add integration test
• Consider: should SimpleGuard accept api_key and auto-register if agent_id is not provided?

Related

• Server endpoint: capiscio-server/internal/api/router.go line 195
• gRPC proto: capiscio-core/proto/capiscio/v1/registry.proto

Labels

enhancement, developer-experience