How swamiabhishek45/kikoyu-agent-sdk works
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: runner.ts Runner · run/route.ts Run Endpoint · stream/route.ts Stream Endpoint · register/route.ts Register Endpoint
Components 26
HTTP API
- Run Endpoint
packages/api/app/api/agents/run/route.ts - Stream Endpoint
packages/api/app/api/agents/stream/route.ts - Register Endpoint
packages/api/app/api/agents/register/route.ts - API Key Auth
packages/api/lib/auth.ts - Agent Resolver
packages/api/lib/agent-resolver.ts - Agent Registry
packages/api/lib/agent-registry.ts
Agent Orchestration
- Agent Builder
packages/core/src/agent-builder.ts - Agent
packages/core/src/agent.ts - Runner
packages/core/src/runner.ts - Handoffs
packages/core/src/handoff.ts
Agent Capabilities
- Guardrails
packages/core/src/guardrail.ts - Tool Execution
packages/core/src/tool.ts - Tool Registry
packages/core/src/tool-registry.ts - Structured Output
packages/core/src/structured-output.ts
Model Providers
- Provider Interface
packages/core/src/providers/index.ts - OpenAI Provider
packages/core/src/providers/openai.ts - Anthropic Provider
packages/core/src/providers/anthropic.ts - Gemini Provider
packages/core/src/providers/gemini.ts - Fallback Provider
packages/core/src/providers/fallback.ts
State and Tracing
- Run Context
packages/core/src/run-context.ts - Session
packages/core/src/session.ts - Memory Store
packages/core/src/memory.ts - Tracing
packages/core/src/tracing.ts - Stream Events
packages/core/src/stream-event.ts
Other components
- API Caller
- Model APIs
Connections 36
- 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