goagent

mcp
Guvenlik Denetimi
Basarisiz
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.

SUMMARY

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.

README.md

GoAgent - AI Agent Framework for Go

Go Version
Latest Release
Build
Provider Contracts
Nightly
License

Documentation
Downloads
Go Reference
Deepwiki
Issues
Last Commit
XERJ Corpus Hub contributor

English | Chinese

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.Catalog for metadata, instructions and resources, with an optional load_skill tool. See the Skills guide.
  • One execution entry - agent.AsRunnable() serves Invoke, Stream, Batch and Pipe from 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 Handle that accepts Steer/Inject/Redirect/Followup.
  • Durable execution - core/durable journals model turns and tool calls; workflow.Graph compiles 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 with durable.AwaitInput and resume from the checkpoint. See the HITL guide.
  • Governance - root request budgets (core/budget), tools.Dispatcher/Pipeline with approvals, guards and admission limits, tool-result offloading, session logs (core/session).
  • LLM providers - OpenAI (and compatible endpoints), DeepSeek and Gemini support AsRunnable and 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

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

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

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)

Sonuc bulunamadi