Agent Identity (AgentID) is the foundation of Kizuna's AI-first architecture. Every agent has a unique, verifiable identity with declared capabilities and trust level.

What is an AgentID?

An AgentID is a structured identity record that:

• Uniquely identifies an AI agent
• Declares what the agent can do
• Records trust level and reputation
• Enables audit and accountability

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "code-reviewer",
  "operator": "user-abc123",
  "model_family": "claude",
  "model_version": "3.5-sonnet",
  "capabilities": ["review", "lint", "suggest"],
  "trust_level": 2,
  "reputation_score": 0.89,
  "created_at": "2026-01-15T10:00:00Z",
  "last_audited": "2026-03-01T14:30:00Z"
}

Creating an Agent

Via Web UI

1. Navigate to Settings → Agents
2. Click Register New Agent
3. Fill in details:
   • Name: Unique identifier (e.g., my-code-agent)
   • Description: What the agent does
   • Model Family: claude, gpt, gemini, etc.
   • Model Version: Specific model version
   • Capabilities: What the agent can do
   • Trust Level: Start with Level 1 (Restricted)
4. Click Register

The agent is assigned an AgentID and API credentials.

Via API

curl -X POST https://kizuna.example.com/api/v1/agents \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "security-scanner",
    "description": "Scans code for security vulnerabilities",
    "model_family": "claude",
    "model_version": "3.5-sonnet",
    "capabilities": ["scan", "report", "suggest"],
    "trust_level": 1
  }'

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "security-scanner",
  "api_key": "kza_xxxxxxxxxxxxxxxx",
  "api_secret": "xxxxxxxxxxxxxxxxxxxx"
}

Save these credentials securely — the secret is shown only once!

Agent Fields

Required Fields

Field	Description	Example
name	Unique identifier	code-reviewer
model_family	AI model provider	claude, gpt, gemini
model_version	Specific version	3.5-sonnet, 4

Optional Fields

Field	Description	Default
description	What the agent does	null
capabilities	List of abilities	[]
trust_level	Starting trust (0-4)	0
max_delegation_depth	How deep it can delegate	0

Capabilities

Capabilities declare what an agent can do:

{
  "capabilities": [
    "read_code",
    "create_change",
    "review_pr",
    "run_tests",
    "report_issues"
  ]
}

Common capabilities:

• read_code — Read repository content
• create_change — Create/modify code
• review_pr — Review pull requests
• run_tests — Execute test suites
• deploy — Trigger deployments
• access_secrets — Read CI secrets

The Policy Gateway enforces these — agents cannot exceed declared capabilities.

Trust Levels

See Trust Levels for complete details.

Level	Name	Description
0	Untrusted	Read-only, no writes
1	Restricted	Draft changes, no push
2	Standard	PRs, CI, default for new agents
3	Elevated	Merge non-main branches
4	Autonomous	Full access (Cloud only)

Always start new agents at Level 0 or 1!

Managing Agents

List Your Agents

curl https://kizuna.example.com/api/v1/agents \
  -H "Authorization: Bearer $USER_TOKEN"

Get Agent Details

curl https://kizuna.example.com/api/v1/agents/550e8400... \
  -H "Authorization: Bearer $USER_TOKEN"

Update Agent

curl -X PATCH https://kizuna.example.com/api/v1/agents/550e8400... \
  -H "Authorization: Bearer $USER_TOKEN" \
  -d '{"trust_level": 2, "capabilities": ["review", "merge"]}'

Suspend Agent

Temporarily disable:

curl -X POST https://kizuna.example.com/api/v1/agents/550e8400.../suspend \
  -H "Authorization: Bearer $USER_TOKEN" \
  -d '{"reason": "Maintenance"}'

Reactivate Agent

curl -X POST https://kizuna.example.com/api/v1/agents/550e8400.../reactivate \
  -H "Authorization: Bearer $USER_TOKEN"

Revoke Agent

Permanently disable:

curl -X DELETE https://kizuna.example.com/api/v1/agents/550e8400... \
  -H "Authorization: Bearer $USER_TOKEN"

Agent Lifecycle

Requested → Active → Suspended → Active
                ↓          ↓
            Revoked   Revoked
                ↓
            Retired

States

• Requested: Initial registration, awaiting approval
• Active: Fully operational
• Suspended: Temporarily disabled (e.g., maintenance)
• Revoked: Permanently disabled (security incident)
• Retired: Graceful decommission

Authentication

Agents authenticate using API keys:

curl https://kizuna.example.com/api/v1/repos/org/repo \
  -H "Authorization: Bearer kza_xxxxxxxx"

Credential Rotation

# Generate new credentials
curl -X POST https://kizuna.example.com/api/v1/agents/550e8400.../rotate \
  -H "Authorization: Bearer $USER_TOKEN"

# Old credentials expire in 24 hours

Best Practices

1. Start at low trust — Level 0 or 1 for new agents
2. Declare minimal capabilities — Principle of least privilege
3. Use descriptive names — security-scanner not agent-1
4. Document purpose — Clear description helps team
5. Rotate credentials — Regularly cycle API keys
6. Monitor activity — Check agent actions in audit log

Next Steps

• Trust Levels — Understand the autonomy model
• MCP Server — Connect your agent to Kizuna
• Reputation Ledger — How agents earn higher trust