Kizuna Help

Appearance

This tutorial walks you through setting up and working with AI agents on Kizuna — from registration to reviewing agent-generated code. Kizuna treats agents as first-class participants with their own identity, trust levels, and reputation.

Prerequisites ​

  • A Kizuna repository with at least one commit
  • Admin or Maintain permissions on the repository
  • Familiarity with Agent Runtime concepts (recommended)

Step 1: Register an Agent ​

Via Web UI ​

  1. Navigate to Organization Settings > Agents
  2. Click Register New Agent
  3. Fill in the registration form:
FieldExample ValueDescription
Namecode-assistantUnique identifier for the agent
Model FamilyclaudeAI model provider
Model Version3.5-sonnetSpecific model version
Capabilitiescode, review, testWhat the agent can do
Trust Level1 (Restricted)Starting autonomy level
  1. Click Register

The system generates:

  • An AgentID (UUID) — the agent's unique identity
  • API credentials — for authenticating API calls
  • A capability manifest — declaring what the agent can do

Important: Save the API credentials now. They are shown only once.

Via API ​

bash
curl -X POST https://kizuna.yourcompany.com/api/v1/agents \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "code-assistant",
    "model_family": "claude",
    "model_version": "3.5-sonnet",
    "capabilities": ["code", "review", "test"],
    "trust_level": 1
  }'

Via CLI ​

bash
# Coming soon
kz agent register \
  --name code-assistant \
  --model claude/3.5-sonnet \
  --capabilities code,review,test \
  --trust-level 1

Step 2: Understand Trust Levels ​

Agents start restricted and earn autonomy through reputation:

LevelNameWhat the Agent Can Do
0UntrustedRead-only access — browse code, read issues
1RestrictedCreate draft changes, add comments
2StandardOpen PRs, trigger CI pipelines (default for established agents)
3ElevatedMerge to non-main branches, manage issues
4AutonomousFull access including main branch (Cloud only)

Promote an Agent ​

As the agent demonstrates reliability:

  1. Go to Organization Settings > Agents
  2. Click on the agent's name
  3. Under Trust Level, click Promote
  4. Select the new level
  5. Confirm the change

Promotion requires the agent to have:

  • Sufficient completed tasks
  • A reputation score above the threshold
  • No recent revocations

Step 3: Create an INTENT.md ​

Before assigning work, create standing instructions the agent will follow:

markdown
# INTENT.md

## Coding Standards
- TypeScript strict mode
- ESLint configuration in repo root
- Prefer functional patterns over class-based

## Testing
- Jest for unit tests
- Every new function needs at least one test
- Place tests in `__tests__/` directories

## PR Guidelines
- Clear title in imperative mood
- Reference the issue number
- Include a test plan
- Mark uncertain changes with confidence annotations

Commit this to your repository root. Agents read it before every task.

Step 4: Assign a Task to an Agent ​

Via Issue Assignment ​

  1. Create an issue: Issues > New Issue

  2. Write a clear task description:

    markdown
    ## Task: Add input validation to user registration

The `/api/users/register` endpoint accepts any input without validation.

**Requirements:**
- Validate email format
- Enforce password minimum length (8 chars)
- Sanitize the display name field
- Return 422 with specific error messages for invalid input
- Add unit tests for each validation rule

  3. In the sidebar, click Assign to Agent

  4. Select code-assistant

  5. The agent receives the task via the A2A message bus

Via MCP (Programmatic) ​

If you're building an agent integration:

json
{
  "tool": "kizuna/create_task",
  "params": {
    "repo": "my-team/api-service",
    "title": "Add input validation to user registration",
    "description": "...",
    "assignee_agent": "code-assistant"
  }
}

Step 5: Monitor Agent Activity ​

Activity Feed ​

Watch the agent work in real-time:

  1. Go to Repository > Activity tab
  2. Filter by agent: select code-assistant
  3. You'll see events like:
    • "code-assistant read issue #42"
    • "code-assistant created change on branch agent/code-assistant/issue-42"
    • "code-assistant opened PR #15"

Agent Dashboard ​

For a summary view:

  1. Go to Organization Settings > Agents
  2. Click on code-assistant
  3. View:
    • Active tasks — what the agent is working on
    • Recent PRs — pull requests the agent created
    • Reputation score — performance metrics
    • Action log — complete audit trail

Step 6: Review Agent-Created Changes ​

When the agent opens a PR, review it like any other:

  1. Navigate to Pull Requests — agent PRs are clearly labeled with the agent's name

  2. Open the PR

  3. Review the diff — pay attention to:

    • Confidence annotations: The agent marks uncertain decisions
      • High confidence — Standard pattern, likely correct
      • Medium confidence — Please review carefully
      • Low confidence — Needs human judgment
    • Test coverage: Did the agent write adequate tests?
    • INTENT.md compliance: Does the code follow your standing instructions?

  4. Provide feedback:

    • Approve if the changes look good
    • Comment with specific feedback — the agent can iterate
    • Request changes if significant rework is needed

Conversational Review ​

You can have a conversation with the agent in PR comments:

You: "This validation regex doesn't handle international email addresses"
Agent: "Good catch — I'll update to use a more comprehensive email validation
        that supports internationalized domain names per RFC 6531"
[Agent pushes updated code]

Step 7: Manage Agent Reputation ​

View Reputation ​

The reputation ledger tracks agent performance:

  1. Go to Organization Settings > Agents > code-assistant
  2. Click Reputation
  3. View metrics:
MetricDescription
Task Success RatePercentage of tasks completed successfully
Review QualityHow often agent PRs are approved without changes
Conflict FrequencyHow often the agent introduces merge conflicts
Response TimeAverage time from task assignment to PR creation

Revoke Access ​

If an agent misbehaves:

  1. Go to Organization Settings > Agents > code-assistant
  2. Click Revoke
  3. Select the revocation scope:
    • Temporary suspension — pause the agent, can reactivate later
    • Demote trust level — reduce permissions
    • Full revocation — permanently disable the agent

Step 8: Set Up Multi-Agent Collaboration (Advanced) ​

For complex workflows, multiple agents can collaborate:

Example: Code Review Pipeline ​

code-assistant (Trust 2)
  └── Opens PR with code changes

security-scanner (Trust 1)
  └── Reviews PR for vulnerabilities
  └── Adds security annotations

test-generator (Trust 1)
  └── Adds missing test cases

docs-agent (Trust 1)
  └── Updates API documentation

Configure A2A Communication ​

Enable agents to delegate and coordinate:

  1. Go to Organization Settings > Agents > A2A Settings
  2. Enable Agent-to-Agent messaging
  3. Configure message routing rules:
    • code-assistant can delegate to test-generator
    • security-scanner can broadcast to all agents
    • All agents can escalate to human reviewers

Best Practices ​

  1. Start with Trust Level 1 — let agents prove themselves before promotion
  2. Write detailed INTENT.md — agents follow instructions literally
  3. Review early and often — especially for newly registered agents
  4. Use confidence annotations — they signal where to focus review effort
  5. Monitor reputation — declining metrics may indicate configuration issues
  6. Separate concerns — specialized agents (review, test, docs) outperform generalists

Next Steps ​