{"id":48218562,"url":"https://github.com/codeany-ai/open-agent-sdk-go","last_synced_at":"2026-04-05T20:00:31.562Z","repository":{"id":348630681,"uuid":"1198299517","full_name":"codeany-ai/open-agent-sdk-go","owner":"codeany-ai","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-03T16:05:20.000Z","size":151,"stargazers_count":111,"open_issues_count":0,"forks_count":17,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-04T19:57:37.540Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codeany-ai.png","metadata":{"files":{"readme":"README.md","changelog":"history/history.go","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-01T09:43:58.000Z","updated_at":"2026-04-04T17:12:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/codeany-ai/open-agent-sdk-go","commit_stats":null,"previous_names":["codeany-ai/open-agent-sdk-go"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/codeany-ai/open-agent-sdk-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeany-ai%2Fopen-agent-sdk-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeany-ai%2Fopen-agent-sdk-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeany-ai%2Fopen-agent-sdk-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeany-ai%2Fopen-agent-sdk-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codeany-ai","download_url":"https://codeload.github.com/codeany-ai/open-agent-sdk-go/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeany-ai%2Fopen-agent-sdk-go/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31448216,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T15:22:31.103Z","status":"ssl_error","status_checked_at":"2026-04-05T15:22:00.205Z","response_time":75,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-04T19:03:07.350Z","updated_at":"2026-04-05T20:00:31.543Z","avatar_url":"https://github.com/codeany-ai.png","language":"Go","readme":"# Open Agent SDK (Go)\n\nA lightweight, open-source Go SDK for building AI agents. Run the full agent loop in-process — no CLI or subprocess required. Deploy anywhere: cloud, serverless, Docker, CI/CD.\n\nAlso available in [TypeScript](https://github.com/codeany-ai/open-agent-sdk-typescript).\n\n## Features\n\n- **Agent Loop** — Streaming agentic loop with tool execution, multi-turn conversations, and cost tracking\n- **Multi-Provider** — Native support for both Anthropic and OpenAI-compatible APIs (auto-detected)\n- **32 Built-in Tools** — Bash, Read, Write, Edit, Glob, Grep, WebFetch, WebSearch, Agent (subagents), SendMessage, Tasks, Todo, Config, Cron, PlanMode, Worktree, LSP, NotebookEdit, MCP Resources, and more\n- **MCP Support** — Connect to MCP servers via stdio, HTTP, SSE transports, plus in-process SDK server\n- **Permission System** — Configurable tool approval with allow/deny rules, runtime mode changes, filesystem path validation, and directory allowlisting\n- **Hook System** — 11 hook events: PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop, SubagentStop, SubagentStart, PreCompact, Notification, PermissionRequest, PostSampling\n- **Extended Thinking** — Three modes (adaptive, enabled, disabled) with effort levels (low/medium/high/max)\n- **Session Management** — List, get, rename, tag, delete, and fork sessions\n- **Rate Limiting** — Parse API rate limit headers, track utilization, detect rejections\n- **Context Usage** — Track token distribution across messages, tools, and context window percentage\n- **File Checkpointing** — Snapshot and rewind file state to any checkpoint\n- **Sandbox** — Command, file, and network access control\n- **Plugins** — Local plugin loading from manifest files\n- **Cost Tracking** — Per-model token usage, API/tool duration, code change stats\n- **Fallback Model** — Automatic retry with a fallback model on API failure\n- **Subagent System** — Enhanced agent definitions with skills, memory, effort, maxTurns, background mode, per-agent permissions and MCP servers\n- **Custom Tools** — Implement the `Tool` interface to add your own tools\n\n## Quick Start\n\n```bash\ngo get github.com/codeany-ai/open-agent-sdk-go\n```\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"fmt\"\n    \"os\"\n\n    \"github.com/codeany-ai/open-agent-sdk-go/agent\"\n    \"github.com/codeany-ai/open-agent-sdk-go/types\"\n)\n\nfunc main() {\n    a := agent.New(agent.Options{\n        Model:  \"sonnet-4-6\",\n        APIKey: os.Getenv(\"CODEANY_API_KEY\"),\n    })\n    defer a.Close()\n\n    ctx := context.Background()\n\n    // Streaming\n    events, errs := a.Query(ctx, \"What files are in this directory?\")\n    for event := range events {\n        if event.Type == types.MessageTypeAssistant \u0026\u0026 event.Message != nil {\n            fmt.Print(types.ExtractText(event.Message))\n        }\n    }\n    if err := \u003c-errs; err != nil {\n        fmt.Fprintf(os.Stderr, \"Error: %v\\n\", err)\n    }\n\n    // Or use the blocking API\n    result, _ := a.Prompt(ctx, \"Count lines in go.mod\")\n    fmt.Println(result.Text)\n}\n```\n\n## Multi-Provider Support\n\nThe SDK supports both **Anthropic** and **OpenAI-compatible** APIs. The provider is auto-detected based on the base URL, API key prefix, or model name:\n\n```go\n// Anthropic (default)\na := agent.New(agent.Options{\n    Model:  \"sonnet-4-6\",\n    APIKey: os.Getenv(\"ANTHROPIC_API_KEY\"),\n})\n\n// OpenAI\na := agent.New(agent.Options{\n    Model:   \"gpt-4o\",\n    APIKey:  os.Getenv(\"OPENAI_API_KEY\"),\n    BaseURL: \"https://api.openai.com\",\n})\n\n// OpenRouter, DeepSeek, Ollama, etc.\na := agent.New(agent.Options{\n    Model:   \"anthropic/claude-sonnet-4\",\n    APIKey:  os.Getenv(\"OPENROUTER_API_KEY\"),\n    BaseURL: \"https://openrouter.ai/api\",\n})\n```\n\n## Extended Thinking \u0026 Effort\n\n```go\n// Explicit thinking config\na := agent.New(agent.Options{\n    Thinking: \u0026agent.ThinkingConfig{\n        Type:         agent.ThinkingEnabled,\n        BudgetTokens: 10000,\n    },\n})\n\n// Or use effort levels (auto-configures thinking)\na := agent.New(agent.Options{\n    Effort: agent.EffortHigh, // low, medium, high, max\n})\n```\n\n## Fallback Model\n\n```go\na := agent.New(agent.Options{\n    Model:         \"opus-4-6\",\n    FallbackModel: \"sonnet-4-6\", // Auto-retry on failure\n})\n```\n\n## Subagents\n\n```go\na := agent.New(agent.Options{\n    Agents: map[string]agent.AgentDefinition{\n        \"researcher\": {\n            Description:  \"Research agent for deep analysis\",\n            Instructions: \"You are a research specialist...\",\n            Model:        \"opus-4-6\",\n            Tools:        []string{\"Read\", \"Glob\", \"Grep\", \"WebSearch\"},\n            MaxTurns:     20,\n            Effort:       agent.EffortHigh,\n        },\n        \"coder\": {\n            Description:    \"Coding agent for implementation\",\n            Instructions:   \"You are a coding specialist...\",\n            DisallowedTools: []string{\"WebSearch\", \"WebFetch\"},\n            PermissionMode: types.PermissionModeAcceptEdits,\n        },\n    },\n})\n```\n\n## Session Management\n\n```go\nimport \"github.com/codeany-ai/open-agent-sdk-go/session\"\n\nmgr := session.NewManager(\"\")  // default ~/.claude/projects/\n\nsessions, _ := mgr.ListSessions(\"my-project\")\nmessages, _ := mgr.GetSessionMessages(sessions[0].SessionID)\n\nmgr.RenameSession(sessions[0].SessionID, \"New Title\")\nmgr.TagSession(sessions[0].SessionID, strPtr(\"important\"))\n\nfork, _ := mgr.ForkSession(sessions[0].SessionID, \"msg-uuid\", \"Forked Session\")\n```\n\n## Hooks\n\n```go\na := agent.New(agent.Options{\n    Hooks: hooks.HookConfig{\n        PreToolUse: []hooks.HookRule{{\n            Matcher: \"Bash\",\n            Hooks: []hooks.HookFn{\n                func(ctx context.Context, tool string, input map[string]interface{}) (string, error) {\n                    cmd, _ := input[\"command\"].(string)\n                    if strings.Contains(cmd, \"rm -rf\") {\n                        return \"Blocked: dangerous command\", nil\n                    }\n                    return \"\", nil\n                },\n            },\n        }},\n        // Also: PostToolUse, PostToolUseFailure, UserPromptSubmit,\n        // Stop, SubagentStop, SubagentStart, PreCompact,\n        // Notification, PermissionRequest, PostSampling\n    },\n})\n```\n\n## Permissions\n\n```go\nimport \"github.com/codeany-ai/open-agent-sdk-go/permissions\"\n\nconfig := \u0026permissions.Config{\n    Mode: types.PermissionModeDefault,\n    AllowRules: []permissions.Rule{\n        {ToolName: \"Read\"},\n        {ToolName: \"Glob\"},\n        {ToolName: \"Bash\", Pattern: \"git *\"},\n    },\n    DenyRules: []permissions.Rule{\n        {ToolName: \"Bash\", Pattern: \"rm *\"},\n    },\n    AllowedDirs: []string{\"/home/user/projects\"},\n}\n\n// Runtime updates (thread-safe)\nconfig.SetMode(types.PermissionModeAcceptEdits)\nconfig.AddRules([]permissions.Rule{{ToolName: \"Write\"}}, \"allow\")\nconfig.AddDirectories([]string{\"/tmp/workspace\"})\n```\n\n## MCP Servers\n\n```go\na := agent.New(agent.Options{\n    MCPServers: map[string]types.MCPServerConfig{\n        \"filesystem\": {\n            Type:    types.MCPTransportStdio,\n            Command: \"npx\",\n            Args:    []string{\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/tmp\"},\n        },\n        \"api\": {\n            Type: types.MCPTransportHTTP,\n            URL:  \"http://localhost:3000/mcp\",\n        },\n    },\n})\na.Init(ctx) // Connects to MCP servers\n```\n\n### In-Process MCP SDK Server\n\n```go\nimport \"github.com/codeany-ai/open-agent-sdk-go/mcp\"\n\nserver := mcp.NewSdkServer(\"my-tools\", \"1.0.0\")\nserver.RegisterTool(\u0026mcp.SdkMcpTool{\n    Name:        \"get_weather\",\n    Description: \"Get weather for a city\",\n    InputSchema: types.ToolInputSchema{\n        Type:       \"object\",\n        Properties: map[string]interface{}{\n            \"city\": map[string]interface{}{\"type\": \"string\"},\n        },\n        Required: []string{\"city\"},\n    },\n    Handler: func(ctx context.Context, input map[string]interface{}) (*types.ToolResult, error) {\n        city := input[\"city\"].(string)\n        return \u0026types.ToolResult{\n            Content: []types.ContentBlock{{Type: types.ContentBlockText, Text: \"Sunny in \" + city}},\n        }, nil\n    },\n})\n```\n\n## File Checkpointing\n\n```go\nimport \"github.com/codeany-ai/open-agent-sdk-go/checkpoint\"\n\nmgr := checkpoint.NewManager(true)\nmgr.TrackFile(\"/path/to/important/file.go\")\n\nmgr.CreateCheckpoint(\"msg-001\")  // Snapshot current state\n// ... file gets modified ...\nmgr.RewindTo(\"msg-001\")          // Restore to snapshot\n```\n\n## Rate Limiting\n\n```go\nimport \"github.com/codeany-ai/open-agent-sdk-go/ratelimit\"\n\ntracker := ratelimit.NewTracker(func(event ratelimit.RateLimitEvent) {\n    if event.Info.Status == ratelimit.RateLimitRejected {\n        log.Println(\"Rate limited! Resets at:\", event.Info.ResetsAt)\n    }\n})\n\n// Called automatically with API response headers\ntracker.ParseHeaders(resp.Header)\n```\n\n## Sandbox\n\n```go\nimport \"github.com/codeany-ai/open-agent-sdk-go/sandbox\"\n\nvalidator := sandbox.NewValidator(sandbox.Settings{\n    Enabled:          true,\n    ExcludedCommands: []string{\"rm\", \"kill\", \"shutdown\"},\n    Network: \u0026sandbox.NetworkConfig{\n        AllowLocalBinding: true,\n    },\n    IgnoreViolations: \u0026sandbox.IgnoreViolations{\n        NetworkHosts: []string{\"localhost\"},\n    },\n})\n\nvalidator.IsCommandAllowed(\"git status\")  // true\nvalidator.IsCommandAllowed(\"rm -rf /\")    // false\n```\n\n## Custom Tools\n\nImplement the `types.Tool` interface:\n\n```go\ntype MyTool struct{}\n\nfunc (t *MyTool) Name() string                                    { return \"MyTool\" }\nfunc (t *MyTool) Description() string                             { return \"Does something useful\" }\nfunc (t *MyTool) InputSchema() types.ToolInputSchema              { return types.ToolInputSchema{...} }\nfunc (t *MyTool) IsConcurrencySafe(map[string]interface{}) bool   { return true }\nfunc (t *MyTool) IsReadOnly(map[string]interface{}) bool          { return true }\nfunc (t *MyTool) Call(ctx context.Context, input map[string]interface{}, tCtx *types.ToolUseContext) (*types.ToolResult, error) {\n    return \u0026types.ToolResult{\n        Content: []types.ContentBlock{{Type: types.ContentBlockText, Text: \"result\"}},\n    }, nil\n}\n\na := agent.New(agent.Options{\n    CustomTools: []types.Tool{\u0026MyTool{}},\n})\n```\n\n## Examples\n\n| #   | Example                                                   | Description                                      |\n| --- | --------------------------------------------------------- | ------------------------------------------------ |\n| 01  | [Simple Query](examples/01-simple-query/)                 | Streaming query with tool calls                  |\n| 02  | [Multi-Tool](examples/02-multi-tool/)                     | Glob + Bash multi-tool orchestration             |\n| 03  | [Multi-Turn](examples/03-multi-turn/)                     | Multi-turn conversation with session persistence |\n| 04  | [Prompt API](examples/04-prompt-api/)                     | Blocking `Prompt()` for one-shot queries         |\n| 05  | [Custom System Prompt](examples/05-custom-system-prompt/) | Custom system prompt for code review             |\n| 06  | [MCP Server](examples/06-mcp-server/)                     | MCP server integration (stdio transport)         |\n| 07  | [Custom Tools](examples/07-custom-tools/)                 | Define and use custom tools                      |\n| 08  | [One-shot Query](examples/08-official-api-compat/)        | Quick one-shot agent query                       |\n| 09  | [Subagents](examples/09-subagents/)                       | Specialized subagent with restricted tools       |\n| 10  | [Permissions](examples/10-permissions/)                   | Read-only agent with AllowedTools                |\n| 11  | [Web Chat](examples/web/)                                 | Web-based chat UI with streaming                 |\n\nRun any example:\n\n```bash\nexport CODEANY_BASE_URL=https://openrouter.ai/api\nexport CODEANY_API_KEY=your-api-key\nexport CODEANY_MODEL=anthropic/claude-sonnet-4\ngo run ./examples/01-simple-query/\n```\n\n## Architecture\n\n```\nopen-agent-sdk-go/\n├── agent/              # Agent loop, query engine, effort, fallback model\n├── api/                # API client (Anthropic + OpenAI dual protocol)\n├── types/              # Core types: Message, Tool, ContentBlock, MCP\n├── tools/              # 32 built-in tools + registry + executor\n│   └── diff/           # Unified diff generation\n├── mcp/                # MCP client + SDK server + resources + reconnection\n├── permissions/        # Permission rules, runtime management, filesystem validation\n├── hooks/              # 11 hook events with extended hook support\n├── costtracker/        # Token usage and cost tracking\n├── context/            # System/user context injection (git status, CODEANY.md)\n├── history/            # Conversation history persistence (JSONL)\n├── session/            # Session management (list, get, rename, tag, delete, fork)\n├── ratelimit/          # Rate limit header parsing and tracking\n├── contextusage/       # Context window usage tracking\n├── checkpoint/         # File state checkpointing and rewind\n├── sandbox/            # Sandbox access control (commands, files, network)\n├── plugins/            # Local plugin loading and management\n└── examples/           # 11 runnable examples\n```\n\n## Configuration\n\nEnvironment variables:\n\n| Variable                     | Description                                  |\n| ---------------------------- | -------------------------------------------- |\n| `CODEANY_API_KEY`            | API key (required)                           |\n| `CODEANY_MODEL`              | Default model (default: `sonnet-4-6`)        |\n| `CODEANY_BASE_URL`           | API base URL override                        |\n| `CODEANY_CUSTOM_HEADERS`     | Custom headers (comma-separated `key:value`) |\n| `API_TIMEOUT_MS`             | API request timeout in ms                    |\n| `HTTPS_PROXY` / `HTTP_PROXY` | Proxy URL                                    |\n\nAlso supports `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_MODEL` for compatibility.\n\n## Links\n\n- Website: [codeany.ai](https://codeany.ai)\n- TypeScript SDK: [github.com/codeany-ai/open-agent-sdk-typescript](https://github.com/codeany-ai/open-agent-sdk-typescript)\n- Issues: [github.com/codeany-ai/open-agent-sdk-go/issues](https://github.com/codeany-ai/open-agent-sdk-go/issues)\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeany-ai%2Fopen-agent-sdk-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodeany-ai%2Fopen-agent-sdk-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeany-ai%2Fopen-agent-sdk-go/lists"}