# AI use cases for Zhizhi Agent Runtime (cocoyes/zhizhi-agent-runtime) Repo: [cocoyes/zhizhi-agent-runtime](https://github.com/cocoyes/zhizhi-agent-runtime) | Use cases: 4 | Page: https://dedupedai.com/use-cases/cocoyes-zhizhi-agent-runtime/ A model-agnostic Go runtime that turns ordinary Go functions into validated tools and runs planned, dependency-aware agent tasks with guarded side effects. This file holds every use case of this repo. Each one starts with a "## " heading and ends with its URL. - Run a planned multi-step agent task with branches and tests: https://dedupedai.com/use-cases/cocoyes-zhizhi-agent-runtime/run-planned-multistep-agent-demo/ - Add a chat agent to a Go service with one model call: https://dedupedai.com/use-cases/cocoyes-zhizhi-agent-runtime/add-chat-agent-to-go-service/ - Gate an email-sending tool behind confirmation and a guard: https://dedupedai.com/use-cases/cocoyes-zhizhi-agent-runtime/gate-email-send-behind-confirmation/ - Expose MCP server tools to an agent through an allow-list: https://dedupedai.com/use-cases/cocoyes-zhizhi-agent-runtime/expose-mcp-tools-through-allowlist/ ## How to run a planned multi-step agent task with branches and tests with Zhizhi Agent Runtime Repo: [cocoyes/zhizhi-agent-runtime](https://github.com/cocoyes/zhizhi-agent-runtime) | Difficulty: Intermediate | Time: 45 minutes | Basis: From the README Run the full agent example to see planning, conditional branches, and bindings execute end to end. **Who it is for:** A Go developer evaluating whether the runtime can plan dependent steps and skip branches that do not match. **The problem:** Reading about dependency graphs and conditions is not enough. You want to see a complete complex-mode run that you can execute and test. **The outcome:** A working complex-mode run that prints a final answer, plus a passing test for the same example. ### Steps 1. Clone https://github.com/cocoyes/zhizhi-agent-runtime and change into the repo directory. 2. Set the provider settings: `export LLM_BASE_URL="https://your-provider.example/v1"` `export LLM_API_KEY="your-api-key"` `export LLM_MODEL="your-model"` 3. Run the complete workflow: `go run ./examples/10-full-agent` 4. Run the tests for the same example: `go test ./examples/10-full-agent` 5. Read the JSONL trace or the execution statistics in the response to confirm which steps ran and which were skipped. ### Prompt to paste into your agent ```text Clone the zhizhi-agent-runtime repo and set LLM_BASE_URL, LLM_API_KEY, and LLM_MODEL for . Run `go run ./examples/10-full-agent` and report the final answer. Then run `go test ./examples/10-full-agent` and confirm it passes. ``` ### Caveat The runtime never fabricates model responses, so the example needs a real reachable model endpoint and key to produce output. Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/ URL: https://dedupedai.com/use-cases/cocoyes-zhizhi-agent-runtime/run-planned-multistep-agent-demo/ ## How to add a chat agent to a Go service with one model call with Zhizhi Agent Runtime Repo: [cocoyes/zhizhi-agent-runtime](https://github.com/cocoyes/zhizhi-agent-runtime) | Difficulty: Intermediate | Time: 30 minutes | Basis: From the README Wire an OpenAI-compatible model into a Go program with the runtime's Run method. **Who it is for:** A Go backend developer who wants a simple LLM-backed request handler inside an existing service. **The problem:** Calling a chat endpoint directly gives you no structure around tools, retries, or traces. You want a small agent object that wraps the model call. **The outcome:** A Go program that sends a request through the agent and prints the text of the response. ### Steps 1. Install the module: `go get github.com/cocoyes/zhizhi-agent-runtime` 2. Create an openaicompat model from LLM_BASE_URL, LLM_API_KEY, and LLM_MODEL, then build the agent with zhizhi.New(zhizhi.WithModel(model)). 3. Call agent.Run with a zhizhi.Request whose Input is the text to handle, and close the agent when done. 4. Set the three environment variables and run the bundled chat example from the clone: `go run ./examples/00-chat` 5. Optionally set Thinking or ReasoningEffort in openaicompat.Config if your provider supports hybrid reasoning models. ### Prompt to paste into your agent ```text In a Go project, add github.com/cocoyes/zhizhi-agent-runtime and build an agent using openaicompat with LLM_BASE_URL, LLM_API_KEY, and LLM_MODEL. Expose a function that runs through agent.Run and returns response.Text. Verify by running `go run ./examples/00-chat` from a clone and confirming a non-empty reply. ``` ### Caveat The adapter calls {LLM_BASE_URL}/chat/completions, so the provider must expose that path or the calls will fail. Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/ URL: https://dedupedai.com/use-cases/cocoyes-zhizhi-agent-runtime/add-chat-agent-to-go-service/ ## How to gate an email-sending tool behind confirmation and a guard with Zhizhi Agent Runtime Repo: [cocoyes/zhizhi-agent-runtime](https://github.com/cocoyes/zhizhi-agent-runtime) | Difficulty: Advanced | Time: 2 hours | Basis: From the README Declare a high-risk write tool so it runs only after an explicit approval and leaves a receipt. **Who it is for:** A developer building an agent that can send messages on behalf of a user and must not send without approval. **The problem:** An LLM can pick a write tool on its own. You need the runtime to block the side effect until a person or policy approves it. **The outcome:** A send-email tool that returns CONFIRMATION_REQUIRED until approved, and resumes from a checkpoint after approval without repeating completed writes. ### Steps 1. Define the write function with tool.Func and mark it with tool.WithSideEffect(tool.SideEffectWriteNonIdempotent), tool.WithIdempotency(tool.IdempotencyNonIdempotent), tool.WithRisk(tool.RiskHigh), and tool.WithConfirmation(tool.ConfirmationAlways). 2. Build the agent with zhizhi.WithGuard(authorize), zhizhi.WithConfirmation(askUser), and a durable zhizhi.WithCheckpointStore(durableStore) in production. 3. Run the request. If pending.Suspended is true, show the approval request to the user and keep pending.RunID and pending.Checkpoint. 4. After approval, call agent.Resume with zhizhi.ResumeRequest containing RunID, Checkpoint, and Decision set to true, passing the same request-scoped tools. 5. Check the ActionReceipt in the response. Treat UNKNOWN receipts as not successful and do not retry them. ### Prompt to paste into your agent ```text Using github.com/cocoyes/zhizhi-agent-runtime, register a tool with SideEffectWriteNonIdempotent, RiskHigh, and ConfirmationAlways, and wire WithGuard and WithConfirmation. Run a request that asks to send one message and confirm the response contains CONFIRMATION_REQUIRED before approval. Then resume with Decision true and report the ActionReceipt. ``` ### Caveat Without a durable checkpoint store the default store is process-local, so a suspended approval is lost if the process restarts. Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/ URL: https://dedupedai.com/use-cases/cocoyes-zhizhi-agent-runtime/gate-email-send-behind-confirmation/ ## How to expose MCP server tools to an agent through an allow-list with Zhizhi Agent Runtime Repo: [cocoyes/zhizhi-agent-runtime](https://github.com/cocoyes/zhizhi-agent-runtime) | Difficulty: Advanced | Time: 2 hours | Basis: From the README Connect an MCP endpoint and limit which of its tools the agent may call. **Who it is for:** A platform engineer who runs internal MCP tool servers and wants an agent to use only approved tools. **The problem:** MCP servers can expose many tools. You need the agent to see only the subset you trust and to fail safely if the server is unavailable. **The outcome:** An agent configured with one MCP source whose tools are filtered by an allow-list and whose connection behavior is set explicitly. ### Steps 1. Import github.com/cocoyes/zhizhi-agent-runtime/mcp and build a runtimemcp.Config with ID, Transport, Endpoint, and ConnectionStrategy. 2. Set Required to false if the agent should keep working when the server is down, or true if the MCP source is mandatory. 3. Pass the config to the agent with zhizhi.WithMCP alongside zhizhi.WithModel. 4. Add an allow-list so only the MCP tools you approved are visible to planning, using the tool filter options described in the runtime docs. 5. Run a request that needs one of the allowed capabilities and check the trace for which MCP tools were called. ### Prompt to paste into your agent ```text Configure github.com/cocoyes/zhizhi-agent-runtime with a runtimemcp.Config for using streamable HTTP and a lazy connection strategy. Allow only and run one request that needs them. Verify that the JSONL trace shows calls only to allowed tools. ``` ### Caveat The README snippet for MCP is truncated, so confirm the exact allow-list and retry option names in docs/architecture.md or the mcp package before relying on them. Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/ URL: https://dedupedai.com/use-cases/cocoyes-zhizhi-agent-runtime/expose-mcp-tools-through-allowlist/