Repository navigation
Expand file tree
/
Copy pathagenttools.go
More file actions
158 lines (146 loc) · 6.9 KB
/
Copy pathagenttools.go
File metadata and controls
158 lines (146 loc) · 6.9 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
package warmbly
import (
"context"
"encoding/json"
"net/url"
)
// AgentToolService is the AI tool registry over plain HTTP, for
// function-calling agents that do not speak MCP: Hermes-style models,
// OpenAI-compatible frameworks, LangChain executors, plain scripts. It is the
// same registry that POST /v1/mcp exposes, gated the same way, so a tool
// behaves identically whichever door it came through.
//
// There is no route-level scope on these endpoints. Each tool enforces its own
// permission — the API-key scope for key and OAuth callers, the organization
// permission for session callers — and [AgentToolService.List] only ever shows
// what the caller may use, so the whole list can be handed to a model as-is.
// Send-class tools (anything that puts real mail on the wire) are never listed
// and never callable here: an agent wired through this surface can read,
// search, label and draft, but a human presses send.
//
// A call runs as the caller with their permissions, exactly as the matching
// REST route would; a tool can never do more than the credential could through
// the normal API. Write-class tools audit like the routes they wrap.
type AgentToolService service
// AgentTool is one registry tool the caller is permitted to use, as returned
// by [AgentToolService.List].
//
// The server does not report a tool's risk class or the scope it checks; the
// list is already filtered to what the credential allows, so everything in it
// is callable with the same credential.
type AgentTool struct {
// Name is the identifier to pass to [AgentToolService.Call].
Name string `json:"name"`
// Description is the model-facing explanation of what the tool does and
// when to use it.
Description string `json:"description"`
// InputSchema is the JSON Schema of the argument object, kept verbatim so
// it drops into a function-calling client unchanged. It is always an
// object schema; a tool with no arguments has an empty properties map.
InputSchema json.RawMessage `json:"input_schema"`
}
// Function converts the tool to the OpenAI function-calling shape, without a
// round trip to the server. It is what [AgentToolService.ListFunctions]
// returns, built locally.
func (t AgentTool) Function() AgentToolFunction {
return AgentToolFunction{
Type: "function",
Function: AgentToolFunctionSpec{
Name: t.Name,
Description: t.Description,
Parameters: t.InputSchema,
},
}
}
// AgentToolFunctions converts a tool list to OpenAI function-calling objects,
// for a client that fetched the default shape and also wants the manifest.
func AgentToolFunctions(tools []AgentTool) []AgentToolFunction {
out := make([]AgentToolFunction, 0, len(tools))
for _, t := range tools {
out = append(out, t.Function())
}
return out
}
// AgentToolFunction is a tool in OpenAI function-calling form:
// {"type":"function","function":{...}}. The objects go verbatim into an
// OpenAI-compatible tools array or a Hermes <tools> block.
type AgentToolFunction struct {
// Type is always "function".
Type string `json:"type"`
Function AgentToolFunctionSpec `json:"function"`
}
// AgentToolFunctionSpec is the function half of an [AgentToolFunction].
type AgentToolFunctionSpec struct {
Name string `json:"name"`
Description string `json:"description"`
// Parameters is the argument JSON Schema, the same bytes as
// [AgentTool.InputSchema].
Parameters json.RawMessage `json:"parameters"`
}
// AgentToolCallResult is what one tool call returned.
type AgentToolCallResult struct {
// Name echoes the tool that ran.
Name string `json:"name"`
// Result is the tool's output. It is the tool's JSON embedded directly
// when the tool produced JSON (every registry tool does today) and a JSON
// string otherwise, so it is always valid JSON and can be fed back to the
// model as the tool-call result unchanged.
Result json.RawMessage `json:"result"`
}
// Decode unmarshals the tool's output into v, for callers that know the shape
// a particular tool produces.
func (r *AgentToolCallResult) Decode(v any) error {
return json.Unmarshal(r.Result, v)
}
// List returns the tools the caller's credential may use, in registry order,
// in the default {name, description, input_schema} shape. Use [AgentTool.Function]
// or [AgentToolFunctions] to convert locally, or [AgentToolService.ListFunctions]
// to have the server do it.
//
// Fetch it once at session start: the set only changes when the credential's
// scopes do. The read rate limit applies.
func (s *AgentToolService) List(ctx context.Context, opts ...RequestOption) ([]AgentTool, *Response, error) {
return fetchData[AgentTool](ctx, s.client, "ai/tools", opts)
}
// ListFunctions is [AgentToolService.List] with the server rendering OpenAI
// function-calling objects (GET /ai/tools?format=openai), ready for an
// OpenAI-compatible tools array or a Hermes <tools> block. The filtering is
// identical; only the shape differs.
func (s *AgentToolService) ListFunctions(ctx context.Context, opts ...RequestOption) ([]AgentToolFunction, *Response, error) {
opts = append([]RequestOption{WithQueryParam("format", "openai")}, opts...)
return fetchData[AgentToolFunction](ctx, s.client, "ai/tools", opts)
}
// Call runs one tool by name. args is the tool's argument object exactly as the
// model produced it — a map, a struct, or the raw [json.RawMessage] from the
// model's tool call — and must encode to a JSON object matching the tool's
// [AgentTool.InputSchema]. A nil args sends no body, which the server treats as
// no arguments.
//
// Failures map onto the package sentinels:
//
// - [ErrNotFound] (404, code "not_found"): no such tool. A send-class tool
// answers the same way on purpose, so a name a model saw elsewhere (for
// example the dashboard assistant's send_reply) is indistinguishable from
// a typo here.
// - [ErrForbidden] (403, code "forbidden"): the credential lacks the tool's
// permission. It would not have appeared in [AgentToolService.List].
// - [ErrBadRequest] (400, code "bad_request"): the body was not valid JSON.
// - [ErrUnprocessable] (422, code "unprocessable"): the tool itself failed —
// arguments that decoded but did not validate, a missing record, an
// entitlement the workspace lacks. The [Error.Message] is written for the
// model to read and react to; feed it back as the tool result rather than
// treating it as a transport error.
//
// Calls run under the write rate limit and honor [WithIdempotencyKey] like
// every other mutating request, so a retried call with the same key replays
// the stored result instead of running the tool again.
func (s *AgentToolService) Call(ctx context.Context, name string, args any, opts ...RequestOption) (*AgentToolCallResult, *Response, error) {
var env struct {
Data AgentToolCallResult `json:"data"`
}
resp, err := s.client.post(ctx, "ai/tools/"+url.PathEscape(name)+"/call", args, &env, opts...)
if err != nil {
return nil, resp, err
}
return &env.Data, resp, nil
}