goagent
Health Uyari
- License — License: Apache-2.0
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Low visibility — Only 9 GitHub stars
Code Basarisiz
- child_process — Shell command execution capability in .github/workflows/pr.yml
- execSync — Synchronous shell command execution in .github/workflows/pr.yml
- fs module — File system access in .github/workflows/pr.yml
Permissions Gecti
- Permissions — No dangerous permissions requested
Bu listing icin henuz AI raporu yok.
Recoverable, budgeted and observable AI agent execution kernel for Go: native tool loop, durable workflow graphs with checkpoints & human approvals, request budgets, OpenTelemetry, MCP and A2A.
GoAgent - AI Agent Framework for Go
Quick Start · API Reference · Examples · Changelog
Architecture · Development Guide · Testing Guide · Provider Capabilities
GoAgent is a recoverable, budgeted and observable agent execution kernel for Go services: a native tool loop, typed workflow graphs with durable checkpoints and approvals, request budgets, session logs, OpenTelemetry events and MCP.
Related repositories:
- goagent-contrib - retrievers (BM25, hybrid, reranking, Qdrant), document loaders, practical tools and the multi-instance Postgres
durable.Store. - goagent-examples - business cases (DevOps, content review, auto-reply, refund recovery, live-model orchestration).
- goagent-harness - presets, plan mode, compaction, Skills assembly, sub-agent components and coding tools. See the Harness migration guide.
Features
- Skills loading - standalone read-only
skills.Catalogfor metadata, instructions and resources, with an optionalload_skilltool. See the Skills guide. - One execution entry -
agent.AsRunnable()servesInvoke,Stream,BatchandPipefrom the same stream source, so tools, retrieval, middleware and callbacks run on one path. - Native tool loop - the model picks tools or answers in a single streaming request (OpenAI, DeepSeek and Gemini providers); optional parallel tool calls and direct-return tools.
- Loop extension points - PreStep, Request, RequestError, TurnStopping hooks, prompt sections/contexts, and a running
Handlethat accepts Steer/Inject/Redirect/Followup. - Durable execution -
core/durablejournals model turns and tool calls;workflow.Graphcompiles typed graphs with branches, parallel joins, bounded loops and approval resume. - Human in the loop - approval gates accept validated human input via
DurableGraph.Resume; nodes, parallel branches, interruptible tools and nested graphs pause mid-execution withdurable.AwaitInputand resume from the checkpoint. See the HITL guide. - Governance - root request budgets (
core/budget),tools.Dispatcher/Pipelinewith approvals, guards and admission limits, tool-result offloading, session logs (core/session). - LLM providers - OpenAI (and compatible endpoints), DeepSeek and Gemini support
AsRunnableand the native tool loop; Kimi, SiliconFlow and Ollama are OpenAI-compatible presets with the same support, and Anthropic uses the official SDK with the same support. See the provider table. - Observability - read-only execution events (
core/observe) and OpenTelemetry integration (observability). - A2A / MCP - connect to external agents and MCP tools, and expose GoAgent through a shared task service with human input, approvals and cancellation. See the protocol adapters guide.
Quick Start
go get github.com/kart-io/goagent
export OPENAI_API_KEY=...
export OPENAI_MODEL=... # optional: OPENAI_BASE_URL for OpenAI-compatible endpoints
package main
import (
"context"
"fmt"
"log"
"time"
"github.com/kart-io/goagent/builder"
"github.com/kart-io/goagent/llm/providers"
)
func main() {
// Reads OPENAI_API_KEY / OPENAI_MODEL / OPENAI_BASE_URL unless set with llm.With* options.
client, err := providers.NewOpenAIWithOptions()
if err != nil {
log.Fatal(err)
}
agent, err := builder.NewSimpleBuilder(client).
WithSystemPrompt("You are a helpful assistant.").
WithMaxIterations(6).
WithTimeout(30 * time.Second).
Build()
if err != nil {
log.Fatal(err)
}
out, err := agent.AsRunnable().Invoke(context.Background(), "Introduce yourself in one sentence.")
if err != nil {
log.Fatal(err)
}
fmt.Println(out.Result)
}
Tools
Tools implement interfaces.Tool (Name, Description, ArgsSchema, Invoke). tools.NewFunctionTool wraps a function:
weather := tools.NewFunctionTool(
"get_weather",
"Look up the current weather for a city",
`{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}`,
func(ctx context.Context, args map[string]interface{}) (interface{}, error) {
city, _ := args["city"].(string)
return map[string]string{"city": city, "weather": "sunny"}, nil
},
)
agent, err := builder.NewSimpleBuilder(client).
WithSystemPrompt("You can look up the weather.").
WithTools(weather).
WithMaxIterations(6). // includes the final answer
WithRequestError(3, builder.RetryTransient(3, func(retry int) time.Duration {
return time.Duration(retry) * 200 * time.Millisecond
})).
Build()
if err != nil {
return err
}
out, err := agent.AsRunnable().Invoke(ctx, "What's the weather in Paris?")
Streaming
ctx, cancel := context.WithCancel(ctx)
defer cancel() // cancel when you stop consuming early
chunks, err := agent.AsRunnable().Stream(ctx, question)
if err != nil {
return err
}
for chunk := range chunks {
if chunk.Error != nil {
return chunk.Error
}
if chunk.Event != nil && chunk.Event.Type == "text" {
fmt.Print(chunk.Event.Delta) // transient text; may precede a tool call
}
if chunk.Done {
fmt.Println(chunk.Data.Result) // final result after middleware and callbacks
}
}
return ctx.Err()
Other event types are sources, step (e.g. tool_start/tool_end) and usage; usage is a cumulative snapshot. See the Quick Start guide and the execution contract.
Pre-configured Agents
agent, err := builder.QuickAgent(client, "You are a helpful assistant.")
chat, err := builder.ChatAgent(client, "Alice")
rag, err := builder.RAGAgent(client, retriever) // DocumentRetriever, a Retrieve method, or VectorStore
AnalysisAgent, WorkflowAgent, MonitoringAgent and ResearchAgent preset prompts, state and middleware the same way.
Grounded RAG
WithRetriever(retriever, builder.RetrievalConfig{MaxDocuments: 4, MaxContextRunes: 12000}) retrieves evidence for every request and returns provenance in the output metadata key retrieval_sources. Retrievers satisfy interfaces.DocumentRetriever; implementations live in goagent-contrib/retrieval. See the RAG and streaming guide.
Running Handle and Loop Hooks
With a llm.ToolStreamClient and at least one tool, agent.Start(ctx, input) runs in the background and returns a *builder.Handle (Steer, Inject, Redirect, Followup, Interrupt, Wait, PendingInputs). PendingInputs snapshots queued, unclaimed input; it is not a durable delivery receipt. Hooks (WithPreStep, WithIdentifiedPreStep, WithRequestHook, WithRequestError, WithTurnStopping, WithPromptSections, WithPromptContexts), tool-result offloading (WithOffload) and session logs (WithSessionLog) are described in the builder README, the context policy guide and core/session.
Durable Execution and Orchestration
- Native orchestration -
workflow.Graph, durable graphs viaAsRunnable, branch-level resume andtools.Dispatcher. - Human in the loop - approval with human input, mid-execution interrupts, checkpoint and failure semantics; offline examples:
examples/human-in-the-loop,examples/human-in-the-loop-interrupt. - Workflow - typed graphs, branches, parallel joins and bounded loops.
- Multi-agent usage -
WithUsageHookfor per-attempt tokens and cumulative statistics, agent identity and unified accounting; examples: goagent-examples/agent-usage. - Multi-agent patterns -
multiagent: Sequential, Loop, RouterSupervisor,ParallelStep,SupervisorToolsand the text relay layer on top ofworkflow; offline example:go run ./examples/multi-agent-patterns. - Composable orchestration - wrap a child agent or
workflow.DurableGraphas a tool withtools.NewRunnableToolFactory; a child waiting for approval suspends the parent withagentErrors.ErrAgentWaiting. - Agent composition and input boundaries - direct workflows, child-agent tools, pending input and completion scopes; Pi design comparison.
- Host integration -
execution.NewScope+execution.ConfigureBuilder+BuildContext; offline example:go run ./examples/execution-scope. - Final validation, governance setup and upgrade checks - final-output validation, governed builders, recovery manifests and scale benchmarks.
- Extension contract and execution governance - budgets, diagnostics and resource limits.
Packages
| Package | Description |
|---|---|
| builder | Fluent agent construction, native tool loop, hooks, Handle |
| builder/contextpolicy | Tool-result offloading (Offload) |
| core | Runnable/StreamRunnable, callbacks, state; subpackages durable, budget, session, observe, middleware |
| execution | Host scope: run/session identity, journal, budget, deadline, observer |
| workflow | Typed graph compilation and durable graphs |
| llm | Client interfaces, options; llm/providers implementations |
| tools | Tool registry, function tools, Dispatcher, Pipeline; tools/policy, tools/spill and built-in tools |
| mcp | MCP client adapter on the official SDK |
| memory | Long-term memory, temporal knowledge graphs, cascading invalidation and indexes; capabilities and migration boundaries |
| harness/env | File system and command execution interfaces for tools |
| observability | OpenTelemetry tracing and metrics |
| evaluation/agentbench | Reproducible task evaluation |
| testing | Mocks, test utilities and session-log replay |
Other packages: cache, errors, interfaces, parsers, store, middleware, devtools, utils.
Documentation
- Quick Start
- User Guide
- Builder API Reference
- HTTP / SSE / WebSocket, Webhooks and Hooks · Design
- LLM Providers
- Execution overhead measurements
See docs/README.md for the full index and CHANGELOG.md for breaking changes.
Examples
Runnable examples live in examples/; business cases live in goagent-examples.
go run ./examples/workflow
Development
git clone https://github.com/kart-io/goagent.git
cd goagent
go test ./...
golangci-lint run
bash scripts/verify_imports.sh # import layering
bash scripts/check_coverage.sh # coverage threshold
License
Apache License 2.0 - see LICENSE.
Support
- Issues: GitHub Issues
Acknowledgments
GoAgent is inspired by LangChain, LangGraph and AutoGen.
See management for unified agent, session, task and approval management and execution observability. Database and Harness adapters remain in extension projects.
Yorumlar (0)
Yorum birakmak icin giris yap.
Yorum birakSonuc bulunamadi