trpc-agent-go

Supports Mcp

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:

# 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

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(...):

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:

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

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)

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.

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
• Controllable graph workflow: examples/graph
• Agent frontend or streaming UI: examples/agui
• A2A interoperability: examples/a2aagent
• RAG and knowledge retrieval: examples/knowledge
• Evaluation and prompt iteration: examples/evaluation
• Skills and local automation: examples/skillrun

1. Tool Usage

• examples/agenttool – Wrap agents as callable tools.
• examples/multitools – Multiple tools orchestration.
• examples/duckduckgo – Web search tool integration.

2. LLM-Only Agent

Example: 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

• 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

• 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:

// 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

• 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

• 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

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

8. MCP Integration

Example: 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.
• Enables dynamic tool execution and context-rich interactions between agents and LLMs.

9. AG-UI Demo

Example: examples/agui

• Exposes a Runner through the AG-UI (Agent-User Interaction) protocol.
• Built-in Server-Sent Events (SSE) server, plus client samples (for example, CopilotKit and TDesign Chat).

10. Evaluation

Example: examples/evaluation

• Evaluate an agent with repeatable eval sets and pluggable metrics.
• Includes local file-backed runs and in-memory runs.

11. Agent Skills

Examples: examples/skillrun, examples/skillfind

• Skills are folders with a SKILL.md spec + optional docs/scripts.
• Built-in tools: skill_load, skill_list_docs, skill_select_docs, skill_run, and (when the executor supports interactive sessions) skill_exec, skill_write_stdin, skill_poll_session, skill_kill_session.
• skill_run is the default one-shot command runner in an isolated workspace.
• skill_exec and the session tools cover interactive stdin/TTY flows without inlining full scripts into the prompt. They are registered only when the code executor exposes InteractiveProgramRunner (or falls back to a local engine that does).
• skill.NewFSRepository(...) can scan multiple roots, such as a shared skills directory plus a user-private directory. Use (*skill.FSRepository).Refresh() after skill installation or removal in long-lived processes.
• Prefer using skill_run only for commands required by the selected skill docs, not for generic shell exploration.
• When LLMAgent uses WithCodeExecutor(...) only to support skill_run, disable the response code execution processor with llmagent.WithEnableCodeExecutionResponseProcessor(false). The skill-focused examples (examples/skill, examples/skillrun, examples/skilldynamicschema, and examples/structuredoutputskills) follow this pattern so fenced code blocks embedded in assistant text do not auto-execute.
• examples/skillfind demonstrates a real end-to-end discovery flow: the model uses a built-in skill-find skill to search the public web, install a public GitHub skill into a user-private directory, refresh the repository, and use the new skill in the same conversation. Local execution stays off by default and can be enabled explicitly when you want to run an installed skill.

12. Agent Self-Evolution

Example: examples/evolution

• Reviews completed sessions in the background and extracts reusable SKILL.md workflows.
• Supports revision storage, quality gates, human approval, and warm-start behavior when skills are available on later runs.
• Runner integration is a single option: runner.WithEvolutionService(...).

13. Artifacts

Example: examples/artifact

• Save and retrieve versioned files (images, text, reports) produced by tools.
• Supports multiple backends (in-memory, S3, COS).

14. A2A Interop

Example: examples/a2aadk

• Agent-to-Agent (A2A) interop with an ADK Python A2A server.
• Demonstrates streaming, tool calls, and code execution across runtimes.

15. Gateway Server

Example: openclaw

• A minimal OpenClaw-like gateway server.
• Stable session ids and per-session serialization.
• Basic safety controls: allowlist + mention gating.
• OpenClaw-like implementation (Telegram + gateway): openclaw

Other notable examples:

• examples/humaninloop – Human in the loop.
• examples/codeexecution – Secure code execution.

See individual README.md files in each example folder for usage details.