Kode Agent SDK for .NET

中文版: 查看中文 README

A powerful AI Agent runtime SDK built on .NET 10, supporting Anthropic Claude and OpenAI GPT models, with comprehensive capabilities for tool calling, state management, event streaming, and more. Designed for building production-grade AI applications.

Project Background

Kode Agent SDK for .NET is the C# implementation of Kode SDK, providing feature parity with the TypeScript version:

• Event-Driven Architecture - Three-channel event system (Progress, Control, Monitor) for separation of concerns
• Complete State Management - Support for persistence, crash recovery, and resumable execution
• Flexible Tool System - 20+ built-in tools with support for custom tools and MCP protocol
• Multi-Model Support - Anthropic Claude, OpenAI GPT, and compatible APIs
• Enterprise Features - Permission control, sandbox execution, dependency injection, logging integration

Table of Contents

• Features
• Sandbox (Local vs Docker)
• Architecture Overview
• Quick Start
• Event Subscriptions
• Custom Tools
• Model Providers
• Dependency Injection
• MCP Integration
• Permission Control
• Built-in Tools
• State Persistence
• Project Structure
• Documentation
• Running Examples
• License
• Contributing
• Community
• Related Links

Features

| Feature | Description | Documentation | | ----------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | Multi-Model Support | Support for Anthropic Claude (Claude 4, 3.5) and OpenAI GPT (GPT-4o, o1) series models, plus compatible APIs | Model Providers | | Rich Tool System | 20+ built-in tools (file system, shell, todo management, etc.), support for custom tools and MCP protocol | Tool Development Guide | | Three-Channel Event Stream | Progress (real-time output), Control (approval flow), Monitor (logging) separated architecture | Event System Details | | State Persistence | JSON file storage and Redis distributed storage, support for session recovery and resumable execution | State Storage | | Permission Control | Fine-grained tool permission management, support for auto-approval, manual approval, and deny policies | Permission Control System | | Sandbox Execution | Secure command execution environment, support for local and Docker sandboxes | Sandbox Environments | | Source Generator | Compile-time tool schema generation, zero reflection overhead, type-safe | Tool Development Guide | | MCP Integration | Native Model Context Protocol support, easy integration with external tool ecosystem | MCP Protocol Integration | | Dependency Injection | Complete Microsoft.Extensions.DependencyInjection support | Dependency Injection | | Template System | Predefined agent templates for quick creation of scenario-specific agents | Sub-Agent Delegation | | Skills System | Progressive skill discovery and activation, dynamic extension of agent capabilities | Skills System | | Sub-Agent Delegation | Support for task delegation to specialized sub-agents, enabling complex workflow orchestration | Sub-Agent Delegation |

Sandbox (Local vs Docker)

The SDK exposes a single ISandbox interface, but you can choose different implementations depending on your risk/performance needs:

| Dimension | LocalSandbox | DockerSandbox | |---|---|---| | Command execution | Runs commands on the host | Runs commands in a dedicated container | | Blast radius | Higher (host-wide if misused) | Lower (container + mounted paths) | | Toolchain | Uses host-installed tools | Depends on Docker image (DockerImage) | | Network | Same as host | Configurable (often none) |

More details: docs/ADVANCED_GUIDE.md#sandbox-environments.

Architecture Overview

graph TB
    subgraph Application["Application Layer"]
        App[Your Application]
    end

    subgraph Agent["Agent Core"]
        AgentCore[Agent]
        Config[AgentConfig]
        State[Runtime State]
        EventBus[EventBus]
        Skills[SkillsManager]
    end

    subgraph Dependencies["Dependencies"]
        Store[(AgentStore)]
        Registry[ToolRegistry]
        Provider[ModelProvider]
        Sandbox[Sandbox]
    end

    subgraph Tools["Tools"]
        Builtin[Builtin Tools]
        Custom[Custom Tools]
        MCP[MCP Tools]
        SkillTools[Skill Tools]
        TaskRun[task_run<br/>Sub-Agent]
    end

    subgraph Providers["Model Providers"]
        Anthropic[Anthropic Claude]
        OpenAI[OpenAI GPT]
        Compatible[Compatible APIs]
    end

    subgraph Storage["Storage"]
        JSON[(JSON Store)]
        Redis[(Redis Store)]
    end

    App --> AgentCore
    AgentCore --> Config
    AgentCore --> State
    AgentCore --> EventBus
    AgentCore --> Skills

    AgentCore --> Store
    AgentCore --> Registry
    AgentCore --> Provider
    AgentCore --> Sandbox

    Registry --> Builtin
    Registry --> Custom
    Registry --> MCP
    Registry --> SkillTools
    Registry --> TaskRun

    Provider --> Anthropic
    Provider --> OpenAI
    Provider --> Compatible

    Store --> JSON
    Store --> Redis

Agent Execution Flow

sequenceDiagram
    participant User
    participant Agent
    participant EventBus
    participant Provider as Model Provider
    participant Tools as Tool Registry

    User->>Agent: RunAsync("User message")
    Agent->>EventBus: Publish(Progress, Start)

    loop Agent Loop
        Agent->>Provider: StreamAsync(messages)
        Provider-->>Agent: Text chunks
        Agent->>EventBus: Publish(Progress, TextChunk)

        alt Tool Call Required
            Provider-->>Agent: ToolUse
            Agent->>EventBus: Publish(Progress, ToolStart)

            alt Requires Approval
                Agent->>EventBus: Publish(Control, ApprovalRequest)
                EventBus-->>Agent: ApprovalResponse
            end

            Agent->>Tools: ExecuteAsync(tool, args)
            Tools-->>Agent: ToolResult
            Agent->>EventBus: Publish(Progress, ToolEnd)
        end
    end

    Agent->>EventBus: Publish(Progress, Done)
    Agent-->>User: AgentRunResult

Quick Start

1. Install Packages

From NuGet.org (Recommended):

# Core packages
dotnet add package Kode.Agent.Sdk
dotnet add package Kode.Agent.Store.Json
dotnet add package Kode.Agent.Tools.Builtin

# Optional: MCP support
dotnet add package Kode.Agent.Mcp

# Optional: Redis storage
dotnet add package Kode.Agent.Store.Redis

From GitHub Packages:

# Configure GitHub Packages source (one-time setup)
dotnet nuget add source \
  --username YOUR_GITHUB_USERNAME \
  --password YOUR_GITHUB_TOKEN \
  --store-password-in-clear-text \
  --name github \
  "https://nuget.pkg.github.com/JinFanZheng/index.json"

# Install packages
dotnet add package Kode.Agent.Sdk --source github

📚 For detailed GitHub Packages setup, see GitHub Packages Guide

Or reference projects directly:

<ProjectReference Include="path/to/Kode.Agent.Sdk.csproj" />
<ProjectReference Include="path/to/Kode.Agent.Store.Json.csproj" />
<ProjectReference Include="path/to/Kode.Agent.Tools.Builtin.csproj" />

2. Configure Environment Variables

Create a .env file (Anthropic Claude recommended):

# Anthropic configuration (recommended)
ANTHROPIC_API_KEY=your-api-key-here
ANTHROPIC_MODEL_ID=claude-sonnet-4-20250514
ANTHROPIC_BASE_URL=https://api.anthropic.com  # Optional, supports custom endpoint

Optional configuration for other providers:

# OpenAI configuration (optiona