trpc-agent-go

About trpc-agent-go

This large README is shown as a plain-text preview. Read the full README at the source

<div align="center">
  <img src="docs/mkdocs/assets/img/logo-readme-blue.png" alt="tRPC logo" width="260">

  <a id="trpc-agent-go"></a>
  <h1>tRPC-Agent-Go</h1>

  <p>
    English | <a href="README.zh_CN.md">中文</a>
  </p>

<p align="center">
  <a href="https://trendshift.io/repositories/15288"><img src="https://trendshift.io/api/badge/repositories/15288" alt="GitHub Trending #3 Repository Of The Day archived by Trendshift" width="250" height="55"></a>
  <a href="https://trendshift.io/repositories/15288"><img src="https://trendshift.io/api/badge/trendshift/repositories/15288/daily?language=Go" alt="Trendshift #1 Go Repository Of The Day" width="250" height="55"></a>
</p>

<p align="center">
  <a href="https://pkg.go.dev/trpc.group/trpc-go/trpc-agent-go"><img src="https://pkg.go.dev/badge/trpc.group/trpc-go/trpc-agent-go.svg" alt="Go Reference"></a>
  <a href="https://github.com/trpc-group/trpc-agent-go/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-green.svg" alt="LICENSE"></a>
  <a href="https://github.com/trpc-group/trpc-agent-go/releases"><img src="https://img.shields.io/github/release/trpc-group/trpc-agent-go.svg?style=flat-square" alt="Releases"></a>
  <a href="https://github.com/trpc-group/trpc-agent-go/actions/workflows/prc.yml"><img src="https://github.com/trpc-group/trpc-agent-go/actions/workflows/prc.yml/badge.svg" alt="Tests"></a>
  <a href="https://app.codecov.io/gh/trpc-group/trpc-agent-go/tree/main"><img src="https://codecov.io/gh/trpc-group/trpc-agent-go/branch/main/graph/badge.svg" alt="Coverage"></a>
  <a href="https://trpc-group.github.io/trpc-agent-go/"><img src="https://img.shields.io/badge/Docs-Website-blue.svg" alt="Documentation"></a>
</p>

  <hr />
</div>

**tRPC-Agent-Go is a Go framework for building production agent systems.**
It provides LLM agents, graph workflows, tool calling, session and memory
state, knowledge retrieval, agent self-evolution, evaluation, and OpenTelemetry
observability in one Go-native stack.

Use it when you want agent applications that fit Go services: concurrent,
observable, easy to deploy, and ready to integrate with A2A, AG-UI, and MCP.

**Why tRPC-Agent-Go?**

- **Go-Native Agent Runtime**: Streaming runners, context cancellation, and
  service-friendly APIs
- **GraphAgent**: Type-safe graph workflows with multi-conditional routing,
  functionally equivalent to LangGraph for Go
- **Multi-Agent Collaboration**: Chain, parallel, and cycle-based workflows
- **Rich Tool Ecosystem**: Function tools, MCP tools, web search, code
  execution, and custom services
- **Persistent State**: Session, memory, artifacts, and knowledge retrieval
- **Agent Skills**: Reusable `SKILL.md` workflows with safe execution
- **Agent Self-Evolution**: Hermes-style session reviews that extract, gate,
  and publish reusable `SKILL.md` workflows
- **Prompt Caching**: Automatic cost optimization with 90% savings on cached content
- **Evaluation & Benchmarks**: Eval sets + metrics to measure quality over time
- **Protocol Integration**: AG-UI for frontends, A2A for agent
  interoperability, and MCP for tools
- **Production Observability**: OpenTelemetry tracing, metrics, and Langfuse
  examples

## Use Cases

**Perfect for building:**

- **Customer Support Bots** - Intelligent agents that understand context and solve complex queries
- **Data Analysis Assistants** - Agents that query databases, generate reports, and provide insights
- **DevOps Automation** - Smart deployment, monitoring, and incident response systems
- **Business Process Automation** - Multi-step workflows with human-in-the-loop capabilities
- **Research & Knowledge Management** - RAG-powered agents for document analysis and Q&A

## Key Features

<table>
<tr>
<td width="50%" valign="top">

### Multi-Agent Orchestration

```go
// Chain agents for complex workflows
pipeline := chainagent.New("pipeline",
    chainagent.WithSubAgents([]agent.Agent{
        analyzer, processor, reporter,
    }))

// Or run them in parallel
parallel := parallelagent.New("concurrent",
    parallelagent.WithSubAgents(tasks))
```

</td>
<td width="50%" valign="top">

### Advanced Memory System

```go
// Persistent memory with search
memory := memorysvc.NewInMemoryService()
agent := llmagent.New("assistant",
    llmagent.WithTools(memory.Tools()),
    llmagent.WithModel(model))

// Memory service managed at runner level
runner := runner.NewRunner("app", agent,
    runner.WithMemoryService(memory))

// Agents remember context across sessions
```

</td>
</tr>
<tr>
<td valign="top">

### Rich Tool Integration

```go
// Any function becomes a tool
calculator := function.NewFunctionTool(
    calculate,
    function.WithName("calculator"),
    function.WithDescription("Math operations"))

// MCP protocol support
mcpTool := mcptool.New(serverConn)
```

</td>
<td valign="top">

### Production Observability

```go
// Start Langfuse integration
clean, _ := langfuse.Start(ctx)
defer clean(ctx)

runner := runner.NewRunner("app", agent)
// Run with Langfuse attributes
events, _ := runner.Run(ctx, "user-1", "session-1", 
    model.NewUserMessage("Hello"),
    agent.WithSpanAttributes(
        attribute.String("langfuse.user.id", "user-1"),
        attribute.String("langfuse.session.id", "session-1"),
    ))
```

</td>
</tr>
<tr>
<td valign="top">

### Agent Skills

```go
// Skills are folders with a SKILL.md spec.
repo, _ := skill.NewFSRepository("./skills")

// Let the agent load and run skills on demand.
tools := []tool.Tool{
    skilltool.NewLoadTool(repo),
    skilltool.NewRunTool(repo, localexec.New()),
}
```

`NewFSRepository` also accepts an HTTP(S) URL (for example, a `.zip` or
`.tar.gz` archive). The payload is downloaded and cached locally (set
`SKILLS_CACHE_DIR` to override the cache location).

`NewFSRepository` also accepts multiple roots, which is useful for
combining shared skills with user-private skills. In a long-lived
process, call `repo.Refresh()` after installing, deleting, or renaming a
skill so the next turn sees the updated skill set.

If you wire Skills through `LLMAgent` with `llmagent.WithCodeExecutor(...)`,
consider also setting
`llmagent.WithEnableCodeExecutionResponseProcessor(false)` so Markdown fenced
code blocks embedded in assistant text do not auto-execute while `skill_run` is
enabled.

</td>
<td valign="top">

### Agent Self-Evolution

```go
repo, _ := skill.NewFSRepository("./managed_skills")
evo := evolution.NewService(reviewerModel,
    evolution.WithManagedSkillsDir("./managed_skills"),
    evolution.WithSkillRepository(repo))
defer evo.Close()

runner := runner.NewRunner("app", agent,
    runner.WithEvolutionService(evo))
```

Completed sessions can be reviewed asynchronously, promoted through quality
gates, and published back as managed Agent Skills for future turns.

</td>
</tr>
<tr>
<td colspan="2" valign="top">

### Evaluation & Benchmarks

```go
evaluator, _ := evaluation.New("app", runner, evaluation.WithNumRuns(3))
defer evaluator.Close()
result, _ := evaluator.Evaluate(ctx, "math-basic")
_ = result.OverallStatus
```

</td>
</tr>
</table>

## Table of Contents

- [tRPC-Agent-Go](#trpc-agent-go)
  - [Use Cases](#use-cases)
  - [Key Features](#key-features)
    - [Multi-Agent Orchestration](#multi-agent-orchestration)
    - [Advanced Memory System](#advanced-memory-system)
    - [Rich Tool Integration](#rich-tool-integration)
    - [Production Observability](#production-observability)
    - [Agent Skills](#agent-skills)
    - [Agent Self-Evolution](#agent-self-evolution)
    - [Evaluation \& Benchmarks](#evaluation--benchmarks)
  - [Table of Contents](#table-of-contents)
  - [Documentation](#documentation)
    - [Blog](#blog)
  - [Quick Start](#quick-start)
    - [Prerequisites](#prerequisites)
    - [Run the Example](#run-the-example)
    - [Basic Usage](#basic-usage)
    - [Stop / Cancel a Run](#stop--cancel-a-run)
  - [Examples](#examples)
    - [1. Tool Usage](#1-tool-usage)
    - [2. LLM-Only Agent](#2-llm-only-agent)
    - [3. Multi-Agent Runners](#3-multi-agent-runners)
    - [4. Graph Agent](#4-graph-agent)
    - [5. Memory](#5-memory)
    - [6. Knowledge](#6-knowledge)
    - [7. Telemetry \& Tracing](#7-telemetry--tracing)
    - [8. MCP Integration](#8-mcp-integration)
    - [9. AG-UI Demo](#9-ag-ui-demo)
    - [10. Evaluation](#10-evaluation)
    - [11. Agent Skills](#11-agent-skills)
    - [12. Agent Self-Evolution](#12-agent-self-evolution)
    - [13. Artifacts](#13-artifacts)
    - [14. A2A Interop](#14-a2a-interop)
    - [15. Gateway Server](#15-gateway-server)
  - [Architecture Overview](#architecture-overview)
    - [**Execution Flow**](#execution-flow)
  - [Using Built-in Agents](#using-built-in-agents)
    - [Multi-Agent Collaboration Example](#multi-agent-collaboration-example)
  - [Contributing](#contributing)
    - [**Ways to Contribute**](#ways-to-contribute)
    - [**Quick Contribution Setup**](#quick-contribution-setup)
  - [Acknowledgements](#acknowledgements)
    - [**Enterprise Validation**](#enterprise-validation)
    - [**Open Source Inspiration**](#open-source-inspiration)
  - [Star History](#star-history)
  - [License](#license)
    - [**GitHub Repository** • **Report Issues** • **Join Discussions**](#github-repository--report-issues--join-discussions)

## Documentation

Ready to dive into tRPC-Agent-Go? Our [documentation](https://trpc-group.github.io/trpc-agent-go/) covers everything from basic concepts to advanced techniques, helping you build powerful AI applications with confidence. Whether you're new to AI agents or an experienced developer, you'll find detailed guides, practical examples, and best practices to accelerate your development journey.

### Blog

These blog posts cover the framework overview, core capabilities, and engineering practices—read as needed:

- [A Go Agent Framework for Building Intelligent AI Applications](docs/mkdocs/en/blog/trpcagentgo.md)
- [GraphAgent Seamlessly Combines AI Workflows and Agents](docs/mkdocs/en/blog/graphagent.md)
- [Quickly Build AG-UI-Based Agent Services](docs/mkdocs/en/blog/agui.md)
- [A Go-Native Implementation of the Anthropic Agent Skills Specification](docs/mkdocs/en/blog/skill.md)
- [Building an Enterprise-Grade, Secure, and Controllable OpenClaw Runtime](docs/mkdocs/en/blog/openclaw.md)
- [A Complete Guide to AI Agent Automated Evaluation Paradigms and Engineering Practice](docs/mkdocs/en/blog/evaluation.md)
- [A Complete Guide to Automated Prompt Iteration and Engineering Practice for AI Agents](docs/mkdocs/en/blog/promptiter.md)

## Quick Start

![AG-UI report agent demo](docs/mkdocs/assets/gif/agui/report.gif)

The demo above shows a tRPC-Agent-Go service streaming agent events to an
AG-UI client while the agent plans, calls tools, and updates the interface.

### Prerequisites

- Go 1.21 or later
- LLM provider API key (OpenAI, DeepSeek, etc.)
- 5 minutes to build your first intelligent agent

### Run the Example

**Get started in 3 simple steps:**

```bash
# 1. Clone and setup
git clone https://github.com/trpc-group/trpc-agent-go.git
cd trpc-agent-go

# 2. Configure your LLM
export OPENAI_API_KEY="your-api-key-here"
export OPENAI_BASE_URL="your-base-url-here"  # Optional

# 3. Run your first agent!
cd examples/runner
go run . -model="gpt-4o-mini" -streaming=true
```

**What you'll see:**

- **Interactive chat** with your AI agent
- **Real-time streaming** responses
- **Tool usage** (calculator + time tools)
- **Multi-turn conversations** with memory

Try asking: "What's the current time? Then calculate 15 \* 23 + 100"

### Basic Usage

```go
package main

import (
    "context"
    "fmt"
    "log"

    "trpc.group/trpc-go/trpc-agent-go/agent/llmagent"
    "trpc.group/trpc-go/trpc-agent-go/model"
    "trpc.group/trpc-go/trpc-agent-go/model/openai"
    "trpc.group/trpc-go/trpc-agent-go/runner"
    "trpc.group/trpc-go/trpc-agent-go/tool"
    "trpc.group/trpc-go/trpc-agent-go/tool/function"
)

func main() {
    // Create model.
    modelInstance := openai.New("deepseek-chat",
        openai.WithVariant(openai.VariantDeepSeek),
    )

    // Create tool.
    calculatorTool := function.NewFunctionTool(
        calculator,
        function.WithName("calculator"),
        function.WithDescription("Execute addition, subtraction, multiplication, and division. "+
            "Parameters: a, b are numeric values, op takes values add/sub/mul/div; "+
            "returns result as the calculation result."),
    )

    // Enable streaming output.
    genConfig := model.GenerationConfig{
        Stream: true,
    }

    // Create Agent.
    agent := llmagent.New("assistant",
        llmagent.WithModel(modelInstance),
        llmagent.WithTools([]tool.Tool{calculatorTool}),
        llmagent.WithGenerationConfig(genConfig),
    )

    // Create Runner.
    runner := runner.NewRunner("calculator-app", agent)

    // Execute conversation.
    ctx := context.Background()
    events, err := runner.Run(ctx,
        "user-001",
        "session-001",
        model.NewUserMessage("Calculate what 2+3 equals"),
    )
    if err != nil {
        log.Fatal(err)
    }

    // Process event stream.
    for event := range events {
        if event.Object == "chat.completion.chunk" {
            fmt.Print(event.Response.Choices[0].Delta.Content)
        }
    }
    fmt.Println()
}

func calculator(ctx context.Context, req calculatorReq) (calculatorRsp, error) {
    var result float64
    switch req.Op {
    case "add", "+":
        result = req.A + req.B
    case "sub", "-":
        result = req.A - req.B
    case "mul", "*":
        result = req.A * req.B
    case "div", "/":
        result = req.A / req.B
	default:
		return calculatorRsp{}, fmt.Errorf("invalid operation: %s", req.Op)
    }
    return calculatorRsp{Result: result}, nil
}

type calculatorReq struct {
    A  float64 `json:"A"  jsonschema:"description=First integer operand,required"`
    B  float64 `json:"B"  jsonschema:"description=Second integer operand,required"`
    Op string  `json:"Op" jsonschema:"description=Operation type,enum=add,enum=sub,enum=mul,enum=div,required"`
}

type calculatorRsp struct {
    Result float64 `json:"result"`
}
```

### Dynamic Agent per Request

Sometimes your Agent must be created **per request** (for example: different
prompt, model, tools, sandbox instance). In that case, you can let Runner build
a fresh Agent for every `Run(...)`:

```go
r := runner.NewRunnerWithAgentFactory(
    "my-app",
    "assistant",
    func(ctx context.Context, ro agent.RunOptions) (agent.Agent, error) {
        // Use ro to build an Agent for this request.
        a := llmagent.New("assistant",
            llmagent.WithInstruction(ro.Instruction),
        )
        return a, nil
    },
)

events, err := r.Run(ctx,
    "user-001",
    "session-001",
    model.NewUserMessage("Hello"),
    agent.WithInstruction("You are a helpful assistant."),
)
_ = events
_ = err
```

### Stop / Cancel a Run

If you want to interrupt a running agent, **cancel the context** you passed to
`Runner.Run` (recommended). This stops model calls and tool calls safely and
lets the runner clean up.

Important: **do not** just “break” your event loop and walk away — the agent
goroutine may keep running and can block on channel writes. Always cancel, then
keep draining the event channel until it is closed.

#### Option A: Ctrl+C (terminal programs)

Convert Ctrl+C into context cancellation:

```go
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
defer stop()

events, err := r.Run(ctx, userID, sessionID, message)
if err != nil {
    return err
}
for range events {
    // Drain until the runner stops (ctx canceled or run completed).
}
```

#### Option B: Cancel from your code

```go
ctx, cancel := context.WithCancel(context.Background())
defer cancel()

events, err := r.Run(ctx, userID, sessionID, message)
if err != nil {
    return err
}

go func() {
    time.Sleep(2 * time.Second)
    cancel()
}()

for range events {
    // Keep draining until the channel is closed.
}
```

#### Option C: Cancel by `requestID` (for servers / background runs)

```go
requestID := "req-123"
events, err := r.Run(ctx, userID, sessionID, message,
    agent.WithRequestID(requestID),
)

mr := r.(runner.ManagedRunner)
_ = mr.Cancel(requestID)
```

For more details (including detached cancellation, resume, and server cancel
routes), see `docs/mkdocs/en/runner.md` and `docs/mkdocs/en/agui.md`.

## Examples

The `examples` directory contains runnable demos covering every major feature.

Not sure where to start? Pick a path by what you want to build:

- First multi-turn agent: [examples/runner](examples/runner)
- Controllable graph workflow: [examples/graph](examples/graph)
- Agent frontend or streaming UI: [examples/agui](examples/agui)
- A2A interoperability: [examples/a2aagent](examples/a2aagent)
- RAG and knowledge retrieval: [examples/knowledge](examples/knowledge)
- Evaluation and prompt iteration: [examples/evaluation](examples/evaluation)
- Skills and local automation: [examples/skillrun](examples/skillrun)

### 1. Tool Usage

- [examples/agenttool](examples/agenttool) – Wrap agents as callable tools.
- [examples/multitools](examples/multitools) – Multiple tools orchestration.
- [examples/duckduckgo](examples/duckduckgo) – Web search tool integration.
- [examples/fileinput](examples/fileinput) – Provide files as inputs.
- [examples/agenttool](examples/agenttool) shows streaming and non-streaming
  patterns.

### 2. LLM-Only Agent

Example: [examples/llmagent](examples/llmagent)

- Wrap any chat-completion model as an `LLMAgent`.
- Configure system instructions, temperature, max tokens, etc.
- Receive incremental `event.Event` updates while the model streams.

### 3. Multi-Agent Runners

Example: [examples/multiagent](examples/multiagent)

- **ChainAgent** – linear pipeline of sub-agents.
- **ParallelAgent** – run sub-agents concurrently and merge results.
- **CycleAgent** – iterate until a termination condition is met.

### 4. Graph Agent

Example: [examples/graph](examples/graph)

- **GraphAgent** – demonstrates building and executing complex, conditional
  workflows using the `graph` and `agent/graph` packages. It shows
  how to construct a graph-based agent, manage state safely, implement
  conditional routing, and orchestrate execution with the Runner.

- Multi-conditional fan-out routing:

```go
// Return multiple branch keys and run targets in parallel.
sg := graph.NewStateGraph(schema)
sg.AddNode("router", func(ctx context.Context, s graph.State) (any, error) {
    return nil, nil
})
sg.AddNode("A", func(ctx context.Context, s graph.State) (any, error) {
    return graph.State{"a": 1}, nil
})
sg.AddNode("B", func(ctx context.Context, s graph.State) (any, error) {
    return graph.State{"b": 1}, nil
})
sg.SetEntryPoint("router")
sg.AddMultiConditionalEdges(
    "router",
    func(ctx context.Context, s graph.State) ([]string, error) {
        return []string{"goA", "goB"}, nil
    },
    map[string]string{"goA": "A", "goB": "B"}, // Path map or ends map
)
sg.SetFinishPoint("A").SetFinishPoint("B")
```

### 5. Memory

Example: [examples/memory](examples/memory)

- In‑memory and Redis memory services with CRUD, search and tool integration.
- How to configure, call tools and customize prompts.

### 6. Knowledge

Example: [examples/knowledge](examples/knowledge)

- Basic RAG example: load sources, embed to a vector store, and search.
- How to use conversation context and tune loading/concurrency options.

### 7. Telemetry & Tracing

Example: [examples/telemetry](examples/telemetry)

- OpenTelemetry hooks across model, tool and runner layers.
- Export traces to OTLP endpoint for real-time analysis.

### 8. MCP Integration

Example: [examples/mcptool](examples/mcptool)

- Wrapper utilities around **trpc-mcp-go**, an implementation of the
  **Model Context Protocol (MCP)**.
- Provides structured prompts, tool calls, resource and session messages that
  follow the MCP specification.

Frequently Asked Questions