Skip to content
Back to search

agentloop

A model's tool-use loop over MCP servers, shared by the memory-format and executive benchmarks

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nodelogicau--agentloop/badge.svg)](/listings/nodelogicau--agentloop)

HTML

<a href="/listings/nodelogicau--agentloop"><img src="/api/listings/nodelogicau--agentloop/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 117 lines
  1. # agentloop
  2. A model's tool-use loop over MCP servers, for the benchmarks of
  3. [particulars](https://github.com/nodelogicau/particulars),
  4. [intentions](https://github.com/nodelogicau/intentions) and
  5. [episodes](https://github.com/nodelogicau/episodes), and for the executive's
  6. benchmark.
  7. Each of these benchmarks measures a system: an agent, taught only by what an
  8. MCP server says, using only the tools that server offers. This module is that
  9. agent. It sends the server's instructions and tools to the model unchanged,
  10. forwards every call, and counts what happened.
  11. It started as a copy in each bench: particulars-bench's `internal/agent` and
  12. `internal/impl`, copied into intentions-bench and then changed on both sides.
  13. This module brings the two copies back together, with the fixes from each.
  14. ## Packages
  15. | Package | What it does |
  16. |---|---|
  17. | `agent` | The loop (`Run`, `Session`, `Complete`) and its providers: the Anthropic Messages API and any OpenAI-compatible Chat Completions endpoint |
  18. | `mcpclient` | Starts a server from a command over stdio (`Start`) or reaches one over Streamable HTTP (`Connect`), and forwards calls, keeping error codes. `Join` offers several servers' tools to one loop. |
  19. | `agenttest` | A scripted model for tests: replies from a function of the request, every request recorded, no model call |
  20. ## The loop
  21. ```go
  22. srv, err := mcpclient.Start(ctx, mcpclient.Command{
  23. Line: mcpclient.Expand(im.Command, "{workspace}", ws),
  24. Dir: ws,
  25. Env: []string{"INTENTIONS_NOW=" + now.Format(time.RFC3339)},
  26. }, mcpclient.Client{Name: "intentions-bench", Version: version})
  27. tools, err := mcpclient.ToolDefs(srv.Tools)
  28. p, err := agent.New(settings, os.Getenv("ANTHROPIC_API_KEY"))
  29. res, err := agent.Run(ctx, p, srv, agent.Request{
  30. Settings: settings, Instructions: srv.Instructions, Phase: phase, User: msg, Tools: tools,
  31. })
  32. ```
  33. What `Run` guarantees, whichever provider is used:
  34. - **Instructions come first.** The server's instructions are the first part
  35. of the system prompt, followed by the phase prompt.
  36. - **Tools are sent as served.** Names, descriptions and schemas are unchanged.
  37. - **Bad calls go back as tool errors and never reach the server.** That
  38. covers a call of a tool that was not offered, and arguments that are not
  39. valid JSON. Both count as calls and as tool errors, and the first three
  40. errors of each tool are kept with their arguments
  41. (`Result.ToolErrorSamples`).
  42. - **Every tool call is answered**, even on the turn where the cap stops the
  43. loop. A later message in a `Session` therefore continues a well-formed
  44. history.
  45. - **Truncation is reported.** `Capped` is set when the turn cap ends the
  46. loop, or when the provider reports output cut at its limit.
  47. - **A refusal ends the loop.** It returns a `*RefusalError` with the turn's
  48. usage.
  49. - **Usage is counted per call**, including cache reads and writes, and the
  50. upstream that served each call when a router names it.
  51. `Session` holds one conversation across several user messages. Each `Send`
  52. runs the loop for one message, and its `Result` counts that message alone.
  53. ## Providers
  54. - `anthropic` (default): the system prompt and tools are marked for prompt
  55. caching, and with tools, so is the conversation so far. `Effort` is sent
  56. as `output_config.effort`.
  57. - `openai`: any Chat Completions endpoint at `BaseURL` (default
  58. `https://api.openai.com/v1`). Tools go as functions with strict mode off.
  59. `Effort` is sent as `reasoning_effort` only when set. `MaxTokens` is sent
  60. as `max_completion_tokens` only when positive.
  61. `ExtraBody` is merged into every request unchanged, for router options such
  62. as pinning an upstream.
  63. ## Several servers in one loop
  64. ```go
  65. j, err := mcpclient.Join(
  66. mcpclient.Named{Name: "particulars", Server: p},
  67. mcpclient.Named{Name: "intentions", Server: i},
  68. mcpclient.Named{Name: "episodes", Server: e, Tools: readOnly},
  69. )
  70. res, err := agent.Run(ctx, provider, j, agent.Request{
  71. Settings: s, Instructions: j.Instructions(), User: msg, Tools: j.Tools(),
  72. })
  73. ```
  74. - **Tool names are prefixed** with the server's name: `particulars__claim_assert`.
  75. - **`Instructions` puts each server's instructions under a heading** that
  76. names its prefix.
  77. - **A call with an unknown prefix is a tool error** that the model can
  78. correct, not a protocol error.
  79. - **Names are checked.** Server names must be lower-case letters and digits,
  80. and every joined name must fit the 64-character limit that providers
  81. share.
  82. ## Comparability
  83. Benchmarks compare results only within one report. A change to this module
  84. can change how an agent behaves, so:
  85. - **Pin a version** in each bench's `go.mod`.
  86. - **Record that version** in each run record, from `runtime/debug.ReadBuildInfo`.
  87. - **Treat an upgrade in the middle of a study as a new configuration.**
  88. ## Development
  89. `make test` runs every test with the race detector and calls no model.
  90. `make lint` runs `go vet` and golangci-lint. The `mcpclient` tests start the
  91. test binary itself as a fake MCP server, so nothing needs to be installed.
  92. ## Licence
  93. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.