# swamiabhishek45/kikoyu-agent-sdk architecture

> Architecture diagram of the GitHub repository swamiabhishek45/kikoyu-agent-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/swamiabhishek45/kikoyu-agent-sdk
- Repository: https://github.com/swamiabhishek45/kikoyu-agent-sdk

## Overview

Kikoyu is a TypeScript AI-agent SDK, with a companion HTTP API. Its main workflow accepts a user prompt, resolves an agent, and runs it through model calls, guardrails, tools, optional handoffs and structured-output handling, returning a result or streaming lifecycle events. Sessions preserve conversation messages; tracing records execution steps. The API also supports agent registration. Runner and API wiring are supported by sampled source; several SDK capabilities and provider integrations are documented but their internal wiring was not sampled, so uncertain links are omitted.

Main entry points: [`packages/core/src/runner.ts`](https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/runner.ts) (Runner), [`packages/api/app/api/agents/run/route.ts`](https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/api/app/api/agents/run/route.ts) (Run Endpoint), [`packages/api/app/api/agents/stream/route.ts`](https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/api/app/api/agents/stream/route.ts) (Stream Endpoint), [`packages/api/app/api/agents/register/route.ts`](https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/api/app/api/agents/register/route.ts) (Register Endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_run_route["Run Endpoint<br/>[route.ts]"]
  node_stream_route["Stream Endpoint<br/>[route.ts]"]
  node_register_route["Register Endpoint<br/>[route.ts]"]
  node_auth["API Key Auth<br/>[auth.ts]"]
  node_resolver["Agent Resolver<br/>[agent-resolver.ts]"]
  node_registry[("Agent Registry<br/>[agent-registry.ts]")]
end

subgraph group_orchestration["Agent Orchestration"]
  node_builder["Agent Builder<br/>[agent-builder.ts]"]
  node_agent["Agent<br/>[agent.ts]"]
  node_runner["Runner<br/>[runner.ts]"]
  node_handoff["Handoffs<br/>[handoff.ts]"]
end

subgraph group_capabilities["Agent Capabilities"]
  node_guardrails["Guardrails<br/>[guardrail.ts]"]
  node_tools["Tool Execution<br/>[tool.ts]"]
  node_tool_registry["Tool Registry<br/>[tool-registry.ts]"]
  node_structured["Structured Output"]
end

subgraph group_models["Model Providers"]
  node_providers["Provider Interface<br/>[index.ts]"]
  node_openai["OpenAI Provider<br/>[openai.ts]"]
  node_anthropic["Anthropic Provider<br/>[anthropic.ts]"]
  node_gemini["Gemini Provider<br/>[gemini.ts]"]
  node_fallback["Fallback Provider<br/>[fallback.ts]"]
end

subgraph group_state["State and Tracing"]
  node_context["Run Context<br/>[run-context.ts]"]
  node_session["Session<br/>[session.ts]"]
  node_memory[("Memory Store<br/>[memory.ts]")]
  node_tracing["Tracing<br/>[tracing.ts]"]
  node_events["Stream Events<br/>[stream-event.ts]"]
end

node_caller(("API Caller"))
node_model_service(("Model APIs"))

node_caller -->|"submits run"| node_run_route
node_caller -->|"requests stream"| node_stream_route
node_caller -->|"registers agent"| node_register_route
node_run_route -->|"validates key"| node_auth
node_stream_route -->|"validates key"| node_auth
node_register_route -->|"validates key"| node_auth
node_run_route -->|"resolves agent"| node_resolver
node_stream_route -->|"resolves agent"| node_resolver
node_resolver -->|"looks up agent"| node_registry
node_register_route -->|"builds agent"| node_builder
node_register_route -->|"creates provider"| node_openai
node_register_route -->|"registers agent"| node_registry
node_resolver -->|"builds inline agent"| node_builder
node_resolver -->|"creates provider"| node_openai
node_run_route -->|"runs agent"| node_runner
node_stream_route -->|"streams agent"| node_runner
node_builder -->|"builds"| node_agent
node_agent -->|"owns tools"| node_tool_registry
node_runner -->|"uses agent"| node_agent
node_runner -->|"creates context"| node_context
node_runner -->|"loads and appends messages"| node_session
node_session -->|"reads and writes"| node_memory
node_runner -->|"records steps"| node_tracing
node_runner -->|"executes checks"| node_guardrails
node_runner -->|"looks up tools"| node_tool_registry
node_runner -->|"executes tool"| node_tools
node_runner -->|"validates and repairs"| node_structured
node_runner -->|"handles transfer"| node_handoff
node_runner -->|"calls model interface"| node_providers
node_openai -->|"sends requests"| node_model_service
node_gemini -->|"sends requests"| node_model_service
node_anthropic -->|"sends requests"| node_model_service
node_fallback -.->|"selects provider"| node_providers
node_runner -->|"yields events"| node_events
node_stream_route -->|"returns event stream"| node_caller
node_run_route -->|"returns result"| node_caller

click node_run_route "https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/api/app/api/agents/run/route.ts"
click node_stream_route "https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/api/app/api/agents/stream/route.ts"
click node_register_route "https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/api/app/api/agents/register/route.ts"
click node_auth "https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/api/lib/auth.ts"
click node_resolver "https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/api/lib/agent-resolver.ts"
click node_registry "https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/api/lib/agent-registry.ts"
click node_builder "https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/agent-builder.ts"
click node_agent "https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/agent.ts"
click node_runner "https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/runner.ts"
click node_handoff "https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/handoff.ts"
click node_guardrails "https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/guardrail.ts"
click node_tools "https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/tool.ts"
click node_tool_registry "https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/tool-registry.ts"
click node_structured "https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/structured-output.ts"
click node_providers "https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/providers/index.ts"
click node_openai "https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/providers/openai.ts"
click node_anthropic "https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/providers/anthropic.ts"
click node_gemini "https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/providers/gemini.ts"
click node_fallback "https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/providers/fallback.ts"
click node_context "https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/run-context.ts"
click node_session "https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/session.ts"
click node_memory "https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/memory.ts"
click node_tracing "https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/tracing.ts"
click node_events "https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/stream-event.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_run_route,node_stream_route,node_register_route,node_auth,node_resolver,node_registry toneBlue
class node_builder,node_agent,node_runner,node_handoff toneAmber
class node_guardrails,node_tools,node_tool_registry,node_structured,node_caller,node_model_service toneMint
class node_providers,node_openai,node_anthropic,node_gemini,node_fallback toneRose
class node_context,node_session,node_memory,node_tracing,node_events toneIndigo
```

## Components

### HTTP API

- [Run Endpoint](https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/api/app/api/agents/run/route.ts): `packages/api/app/api/agents/run/route.ts`
- [Stream Endpoint](https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/api/app/api/agents/stream/route.ts): `packages/api/app/api/agents/stream/route.ts`
- [Register Endpoint](https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/api/app/api/agents/register/route.ts): `packages/api/app/api/agents/register/route.ts`
- [API Key Auth](https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/api/lib/auth.ts): `packages/api/lib/auth.ts`
- [Agent Resolver](https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/api/lib/agent-resolver.ts): `packages/api/lib/agent-resolver.ts`
- [Agent Registry](https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/api/lib/agent-registry.ts): `packages/api/lib/agent-registry.ts`

### Agent Orchestration

- [Agent Builder](https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/agent-builder.ts): `packages/core/src/agent-builder.ts`
- [Agent](https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/agent.ts): `packages/core/src/agent.ts`
- [Runner](https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/runner.ts): `packages/core/src/runner.ts`
- [Handoffs](https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/handoff.ts): `packages/core/src/handoff.ts`

### Agent Capabilities

- [Guardrails](https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/guardrail.ts): `packages/core/src/guardrail.ts`
- [Tool Execution](https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/tool.ts): `packages/core/src/tool.ts`
- [Tool Registry](https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/tool-registry.ts): `packages/core/src/tool-registry.ts`
- [Structured Output](https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/structured-output.ts): `packages/core/src/structured-output.ts`

### Model Providers

- [Provider Interface](https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/providers/index.ts): `packages/core/src/providers/index.ts`
- [OpenAI Provider](https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/providers/openai.ts): `packages/core/src/providers/openai.ts`
- [Anthropic Provider](https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/providers/anthropic.ts): `packages/core/src/providers/anthropic.ts`
- [Gemini Provider](https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/providers/gemini.ts): `packages/core/src/providers/gemini.ts`
- [Fallback Provider](https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/providers/fallback.ts): `packages/core/src/providers/fallback.ts`

### State and Tracing

- [Run Context](https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/run-context.ts): `packages/core/src/run-context.ts`
- [Session](https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/session.ts): `packages/core/src/session.ts`
- [Memory Store](https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/memory.ts): `packages/core/src/memory.ts`
- [Tracing](https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/tracing.ts): `packages/core/src/tracing.ts`
- [Stream Events](https://github.com/swamiabhishek45/kikoyu-agent-sdk/blob/master/packages/core/src/stream-event.ts): `packages/core/src/stream-event.ts`

### Other components

- **API Caller**
- **Model APIs**

## Connections

- API Caller → Run Endpoint: submits run
- API Caller → Stream Endpoint: requests stream
- API Caller → Register Endpoint: registers agent
- Run Endpoint → API Key Auth: validates key
- Stream Endpoint → API Key Auth: validates key
- Register Endpoint → API Key Auth: validates key
- Run Endpoint → Agent Resolver: resolves agent
- Stream Endpoint → Agent Resolver: resolves agent
- Agent Resolver → Agent Registry: looks up agent
- Register Endpoint → Agent Builder: builds agent
- Register Endpoint → OpenAI Provider: creates provider
- Register Endpoint → Agent Registry: registers agent
- Agent Resolver → Agent Builder: builds inline agent
- Agent Resolver → OpenAI Provider: creates provider
- Run Endpoint → Runner: runs agent
- Stream Endpoint → Runner: streams agent
- Agent Builder → Agent: builds
- Agent → Tool Registry: owns tools
- Runner → Agent: uses agent
- Runner → Run Context: creates context
- Runner → Session: loads and appends messages
- Session → Memory Store: reads and writes
- Runner → Tracing: records steps
- Runner → Guardrails: executes checks
- Runner → Tool Registry: looks up tools
- Runner → Tool Execution: executes tool
- Runner → Structured Output: validates and repairs
- Runner → Handoffs: handles transfer
- Runner → Provider Interface: calls model interface
- OpenAI Provider → Model APIs: sends requests
- Gemini Provider → Model APIs: sends requests
- Anthropic Provider → Model APIs: sends requests
- Fallback Provider → Provider Interface: selects provider
- Runner → Stream Events: yields events
- Stream Endpoint → API Caller: returns event stream
- Run Endpoint → API Caller: returns result