UTCP工具

Requirements

• Go 1.25 or newer.
• Network access for network-backed providers.
• Provider-specific runtime dependencies where applicable.

Check the module and examples for transport-specific requirements before deploying a particular provider.

Installation

Install the library with:

go get github.com/universal-tool-calling-protocol/go-utcp@latest

Then import it from Go:

import utcp "github.com/universal-tool-calling-protocol/go-utcp"

CodeMode is available under its plugin package:

import "github.com/universal-tool-calling-protocol/go-utcp/src/plugins/codemode"

Quick start

The smallest useful example can use a local text provider, so no external server is required.

Create providers.json:

{
  "providers": [
    {
      "provider_type": "text",
      "name": "greetings",
      "templates": {
        "hello": "Hello, {{.name}}!"
      }
    }
  ]
}

Create a Go program:

package main

import (
    "context"
    "fmt"
    "log"

    utcp "github.com/universal-tool-calling-protocol/go-utcp"
)

func main() {
    ctx := context.Background()

    client, err := utcp.NewUTCPClient(ctx, &utcp.UtcpClientConfig{
        ProvidersFilePath: "providers.json",
    }, nil, nil)
    if err != nil {
        log.Fatal(err)
    }

    tools, err := client.SearchTools("", 10)
    if err != nil {
        log.Fatal(err)
    }

    for _, tool := range tools {
        fmt.Printf("%s: %s\n", tool.Name, tool.Description)
    }

    result, err := client.CallTool(ctx, "greetings.hello", map[string]any{
        "name": "UTCP",
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(result)
}

Run it with:

go run .

The important detail is the qualified tool name:

<provider>.<tool>

For the example above:

greetings.hello

Provider qualification prevents ambiguous tool names when several providers expose tools with the same local name.

Basic CodeMode example

import "github.com/universal-tool-calling-protocol/go-utcp/src/plugins/codemode"

cm := codemode.NewCodeModeUTCP(client, nil)

result, err := cm.Execute(ctx, codemode.CodeModeArgs{
    Code: `
        value, err := codemode.CallTool("greetings.hello", map[string]any{
            "name": "CodeMode",
        })
        if err != nil {
            __out = err
            return
        }
        __out = value
    `,
    Timeout: 5_000,
})

The exact sandbox restrictions and supported language surface are implementation details and should be checked against the current CodeMode package.

Examples

The examples directory contains standalone examples for providers and transports.

A typical example can be run from its own directory:

cd examples/text_client
GOWORK=off go run -mod=mod .

The GOWORK=off setting is useful when an example is maintained as its own Go module and should use its own dependency graph.

Example categories

Examples cover patterns such as:

• Basic client creation.
• Provider configuration.
• Text tools.
• HTTP providers.
• Streaming.
• MCP integrations.
• CodeMode.
• Transport-specific clients.

Always inspect the example's local README or source before running a network example because some examples expect a local service to be running.

Performance guidelines

• Reuse a client where appropriate.
• Avoid repeatedly discovering the same provider unnecessarily.
• Keep provider metadata scoped to what the application needs.
• Use streaming when incremental results are valuable.
• Apply context deadlines.
• Avoid unnecessary serialization between agent layers.
• Measure the real provider path rather than optimizing only local code.

Repository examples

The examples directory is intentionally part of the documentation surface. When behavior changes, examples should be updated if their assumptions no longer match the implementation.

A good example should:

• Be small.
• Be runnable.
• Show realistic configuration.
• Avoid unnecessary dependencies.
• Explain external prerequisites.
• Demonstrate correct error handling.

CodeMode

CodeMode lets a constrained Go-like program compose multiple tool calls in one execution. This is useful when an agent needs loops, branching, transformation, or multi-step orchestration.

CodeMode

CodeMode provides a controlled execution environment for composing multiple registered tool calls.

The motivation is simple: an agent sometimes needs more than one independent tool invocation. It may need to:

1. Search for resources.
2. Iterate over results.
3. Call another tool for each item.
4. Transform intermediate values.
5. Branch based on results.
6. Return one final value.

Doing every intermediate step through separate model round trips can be expensive. CodeMode moves some orchestration into a constrained program.

CodeMode helpers

CodeMode snippets can use helpers including:

• codemode.CallTool.
• codemode.CallToolStream.
• codemode.SearchTools.

The resulting CodeModeResult contains the produced value and captured output streams.

Why CodeMode?

Without CodeMode, an agent may need to repeatedly request a tool, wait for a result, send the result back to the model, and request the next tool. CodeMode can reduce this orchestration overhead for deterministic multi-step logic.

Tool safety in CodeMode

CodeMode should not be treated as unrestricted host execution. Tool access should remain bounded by the registered provider and the CodeMode execution policy.

Applications embedding CodeMode should carefully define:

• Which tools are available.
• Which providers are trusted.
• Execution timeouts.
• Resource limits.
• Filesystem access.
• Network access.
• Process access.
• Error handling.

Is CodeMode required?

No. CodeMode is an optional plugin for applications that need programmatic multi-tool composition.

Treating CodeMode as unrestricted execution

CodeMode should have explicit tool and execution boundaries.

Provider configuration

ProvidersFilePath can point at a JSON document. The loader accepts several root shapes.

Configuration management

For small applications, a single providers.json file can be sufficient.

For larger deployments, consider generating or assembling provider configuration from:

• Environment-specific templates.
• Secret managers.
• Deployment configuration.
• Service discovery.
• Tenant configuration.

Keep the distinction between configuration and credentials clear.

A provider definition should describe how a capability is reached. A secret manager should provide sensitive values needed to authenticate to it.

Environment variable is not resolved

Check:

• Variable spelling.
• $NAME versus ${NAME} syntax.
• Variables configuration.
• .env path.
• Process environment.
• Configuration load order.

Do not print secret values while debugging.

Client API

The Go API may grow as UTCP evolves. For the authoritative signatures and types, use the package documentation on pkg.go.dev and the source tree.

OpenAPI

The HTTP integration can discover tools from OpenAPI-backed services.

OpenAPI is useful when an existing API already describes operations, parameters, request bodies, and responses through a machine-readable specification.

A practical integration flow is:

OpenAPI document
      |
      v
HTTP provider
      |
      v
UTCP discovery
      |
      v
Tool metadata
      |
      v
Agent / application

When using OpenAPI discovery, keep the generated tool surface intentionally scoped. Large APIs can expose hundreds of operations, and applications may benefit from selecting only the operations required by a particular workflow.

CLI provider fails

Check:

• Executable availability.
• PATH.
• File permissions.
• Working directory.
• Environment variables.
• Argument encoding.
• Process exit status.

For production workloads, prefer narrowly defined commands over arbitrary shell execution.

Minimal reference application

A compact application generally needs only four steps:

ctx := context.Background()

client, err := utcp.NewUTCPClient(ctx, config, nil, nil)
if err != nil {
    return err
}

tools, err := client.SearchTools("", 10)
if err != nil {
    return err
}

_ = tools

result, err := client.CallTool(ctx, "provider.tool", map[string]any{})
if err != nil {
    return err
}

_ = result

This is the core mental model of go-utcp: configure providers, discover tools, select a tool, and call it.

Integration tests

Network-backed integrations should be tested with deterministic local servers where possible.

Tests should cover:

• Successful discovery.
• Successful invocation.
• Invalid configuration.
• Missing tools.
• Provider deregistration.
• Context cancellation.
• Stream completion.
• Stream failure.
• Authentication failures.
• Malformed provider responses.

Go modules

Use the repository's declared Go version and module dependencies. Avoid introducing unnecessary dependencies for functionality that can be implemented with the standard library or existing project abstractions.

Agent integration

go-utcp can act as the tool layer underneath an agent runtime.

A common architecture is:

                   User
                    |
                    v
                 Agent
                    |
              Tool selection
                    |
                    v
               go-utcp
                    |
       +------------+-------------+
       |            |             |
      HTTP         MCP          gRPC
       |            |             |
       v            v             v
    Service      Server        Service

The agent can search available tools rather than hard-coding every integration.

Go-native integration

The library should feel natural in Go applications, using contexts, errors, interfaces, maps, and standard tooling.

Troubleshooting

FAQ

Security review questions

Before exposing a tool to an autonomous caller, ask:

1. What can this tool change?
2. What credentials does it use?
3. What data can it read?
4. Can the operation be reversed?
5. Is it idempotent?
6. What is the blast radius of misuse?
7. Does it need human approval?
8. Can arguments be constrained?
9. Can output contain secrets?
10. What happens if the provider is compromised?

These questions are especially important for filesystem, shell, database, deployment, billing, and administrative tools.