# AgentBase

**Repository Path**: Justlax/agent-base

## Basic Information

- **Project Name**: AgentBase
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-15
- **Last Updated**: 2026-05-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AgentBase

AgentBase 是一个可复用的 C# 后端 Agent 类库，目标是让任意 .NET 项目快速接入一个可流式运行、可调用工具、可切换 provider、可持久化会话的 Agent runtime。

## 已包含

- Agent loop：多轮迭代、流式事件、工具调用、审批、重试、fallback、循环结束状态。
- Provider：OpenAI Chat Completions、OpenAI Responses、Anthropic Messages。
- Responses：reasoning、image generation、computer-use tool call、`previous_response_id` 截图回传。
- Anthropic：text/tool/thinking/signature 流，manual/adaptive thinking 请求配置。
- 工具系统：注册、执行、审批、并发执行。
- 内置工具：`Read`、`Write`、`LS`、`Grep`、`Bash`、`desktop_click`、`desktop_scroll`、`desktop_type`、`desktop_wait`、`desktop_screenshot`、`desktop_move`、`desktop_drag`。
- 持久化通道：`IAgentPersistenceStore`，可外接数据库、对象存储、事件日志。
- 上下文压缩：`IAgentContextCompressor`，默认提供窗口压缩实现。
- Wire/SSE：`AgentWireMapper`、`AgentSseFormatter`。
- Target frameworks：`net8.0`、`net10.0`。

## 基础接入

```csharp
services.AddAgentBase(options =>
{
    options.DefaultProvider = "openai-responses";
    options.Providers["openai-responses"] = new AgentProviderOptions
    {
        Type = AgentProviderTypes.OpenAIResponses,
        Model = "gpt-5.1",
        BaseUrl = "https://api.openai.com/v1",
        ApiKeyEnvironmentVariable = "OPENAI_API_KEY",
        MaxOutputTokens = 4096
    };
});
```

运行 Agent：

```csharp
var runner = serviceProvider.GetRequiredService<IAgentRunner>();

await foreach (var ev in runner.RunAsync(
    [AgentMessage.User("帮我读取 README 并总结")],
    new AgentRunOptions
    {
        SessionId = "session-001",
        WorkingDirectory = @"D:\YourProject",
        MaxProviderAttempts = 3,
        BaseRetryDelay = TimeSpan.FromMilliseconds(1500)
    }))
{
    // 根据 ev.Type 转发给 API、SSE、SignalR 或日志系统
}
```

## 交互式控制台示例

仓库内提供了一个 REPL 风格的控制台 sample：

```powershell
dotnet run --project samples\AgentBase.Console -- --cwd D:\YourProject --provider openai-responses
```

进入后普通输入会持续参与同一个会话：

```text
YourProject> 帮我找出编译错误并修复
YourProject> 继续，把测试也跑一下
```

内置命令：

- `/cwd [path]`：查看或切换工作目录。
- `/provider [name]`：查看或切换 provider。
- `/fallback openai,anthropic`：设置 fallback provider。
- `/session [id]`：查看或切换会话。
- `/reset`：新建会话。
- `/approve prompt|auto|deny`：切换工具审批模式。
- `/history`：查看内存持久化记录。
- `/exit`：退出。

## 持久化通道

默认注册的是 `NoopAgentPersistenceStore`，不落盘。业务项目可以替换成数据库实现：

```csharp
services.AddSingleton<IAgentPersistenceStore, MyDatabaseAgentPersistenceStore>();
```

需要恢复会话历史时：

```csharp
await foreach (var ev in runner.RunAsync(
    [AgentMessage.User("继续上次任务")],
    new AgentRunOptions
    {
        SessionId = "session-001",
        ResumeSession = true
    }))
{
}
```

类库也提供 `InMemoryAgentPersistenceStore`，适合测试或单进程原型。

## Provider fallback

```csharp
await foreach (var ev in runner.RunAsync(
    [AgentMessage.User("执行任务")],
    new AgentRunOptions
    {
        ProviderName = "openai-responses",
        FallbackProviderNames = ["anthropic", "openai"],
        MaxProviderAttempts = 2
    }))
{
}
```

当主 provider 多次失败后，会产生 `provider_fallback` 事件并尝试下一个 provider。

## 上下文压缩

```csharp
new AgentRunOptions
{
    ContextCompression = new AgentContextCompressionOptions
    {
        Enabled = true,
        MaxMessages = 80,
        KeepRecentMessages = 40
    }
};
```

默认实现是窗口压缩：保留 system 消息和最近消息，并插入一条压缩说明。需要更强的摘要策略时，实现 `IAgentContextCompressor` 后注册即可。

## SSE / Wire 输出

```csharp
var seq = 0L;
await foreach (var ev in runner.RunAsync(messages, options))
{
    var sse = AgentSseFormatter.FormatEvent(ev, ++seq, options.SessionId);
    await response.WriteAsync(sse);
}
```

`AgentWireMapper.ToEnvelope()` 会输出稳定 envelope：

- `v`
- `runId`
- `sessionId`
- `seq`
- `events`

## OpenAI Responses image generation

```csharp
options.Providers["openai-responses"].OpenAIResponsesImageGeneration =
    new OpenAIResponsesImageGenerationOptions
    {
        Enabled = true,
        OutputFormat = "png",
        PartialImages = 3,
        Size = "1024x1024",
        Quality = "auto"
    };
```

相关事件：

- `image_generation_started`
- `image_generation_partial`
- `image_generated`
- `image_error`

## OpenAI Responses computer-use

启用 provider-native computer tool：

```csharp
options.Providers["openai-responses"].OpenAIResponsesComputerUseEnabled = true;
```

AgentBase 会把 Responses 的 `computer_call` 映射为内置 `desktop_*` 工具。你需要为真实桌面、浏览器、远程会话或 Playwright 环境注入自己的 `IDesktopAutomation`：

```csharp
services.AddSingleton<IDesktopAutomation, MyDesktopAutomation>();
```

`desktop_screenshot` 的结果会作为 image content block 保存，并在下一轮 Responses 请求中通过 `previous_response_id` + `computer_call_output` 回传给模型。

## Anthropic thinking

Manual thinking：

```csharp
options.Providers["anthropic"].AnthropicThinking = new AnthropicThinkingOptions
{
    Type = "enabled",
    BudgetTokens = 4096
};
```

Adaptive thinking：

```csharp
options.Providers["anthropic"].AnthropicThinking = new AnthropicThinkingOptions
{
    Type = "adaptive",
    Effort = "medium"
};
```

## 扩展工具

```csharp
public sealed class EchoTool : IAgentTool
{
    public ToolDefinition Definition { get; } = ToolDefinition.Create(
        "Echo",
        "Echo text back.",
        new JsonObject { ["text"] = new JsonObject { ["type"] = "string" } },
        required: ["text"]);

    public ValueTask<bool> RequiresApprovalAsync(
        ToolExecutionRequest request,
        AgentToolContext context) => ValueTask.FromResult(false);

    public ValueTask<AgentToolResult> ExecuteAsync(
        ToolExecutionRequest request,
        AgentToolContext context) =>
        ValueTask.FromResult(AgentToolResult.Success(request.Arguments.GetString("text")));
}
```

注册：

```csharp
services.AddSingleton<IAgentTool, EchoTool>();
```

## 验证

```powershell
dotnet test AgentBase.slnx
dotnet pack src\AgentBase\AgentBase.csproj
```