Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
mdx 227 lines 7.68 KB
Raw
1 ---
2 title: Choose and run tools with TypeSafe
3 description: Use Jev to select a Hacker News tool, complete a partial call with a known username, and execute it through Composio.
4 keywords: [typesafe, jev, tool selection, partial calls, hacker news, shortlist]
5 llmGuardrails: direct-execution
6 full: true
7 gallery:
8 categories: [General agents]
9 logos: []
10 featured: true
11 order: 6
12 ---
13
14 Build a script that turns "Look up the Hacker News user 'pg'" into a tool call. TypeSafe's Jev selects the tool. Your code supplies the username, then Composio runs the call.
15
16 This example uses public Hacker News data, so you need no connected account. It follows the runnable [TypeScript examples](https://github.com/ComposioHQ/composio/tree/next/ts/examples/typesafe) and [Python demo](https://github.com/ComposioHQ/composio/blob/next/python/providers/typesafe/typesafe_demo.py).
17
18 ## Set up the script
19
20 Install the [TypeSafe provider](/docs/providers/typesafe#install), then export `COMPOSIO_API_KEY` and `TYPESAFE_API_KEY` in your shell. The TypeScript version requires Node.js 24.17 or newer.
21
22 ## Choose, complete, and execute
23
24 Save the following script. `username` represents a value supplied by your application or a user form. The request asks Jev to choose among three tools, and `knownArguments` supplies values only for the tool they belong to.
25
26 {/* code-example: no-api reason="TypeSafe provider selects and completes the tool call client-side" */}
27 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
28 <Tab value="Python">
29
30 ```python title="select-tool.py"
31 import json
32
33 from composio import Composio
34 from composio_typesafe import TypesafeProvider
35
36 provider = TypesafeProvider()
37 composio = Composio(provider=provider)
38 user_id = "example-user"
39 username = "pg"
40 request = f"Look up the Hacker News user '{username}'"
41 known_arguments = {"HACKERNEWS_GET_USER": {"username": username}}
42
43
44 def main():
45 tool_set = composio.tools.get(
46 user_id=user_id,
47 tools=[
48 "HACKERNEWS_GET_USER",
49 "HACKERNEWS_GET_TOP_STORIES",
50 "HACKERNEWS_SEARCH_POSTS",
51 ],
52 )
53 decision = provider.decide(tool_set, request)
54 print(json.dumps(decision, indent=2))
55
56 if decision["kind"] == "abstain":
57 print(f"No tool call: {decision['reason']}")
58 return
59
60 if decision["risk"] != "read_only":
61 print(f"This example does not execute {decision['risk']} tools.")
62 return
63
64 if decision["kind"] == "partial":
65 print("Arguments to supply:", decision["missing"])
66
67 result = provider.execute(
68 user_id,
69 decision,
70 arguments=known_arguments.get(decision["tool"], {}),
71 )
72 print(result["data"])
73
74
75 if __name__ == "__main__":
76 main()
77 ```
78
79 Run the script in the environment where you installed the packages:
80
81 ```bash
82 python select-tool.py
83 ```
84
85 </Tab>
86 <Tab value="TypeScript">
87
88 ```typescript title="select-tool.ts"
89 import { Composio } from '@composio/core';
90 import { TypesafeProvider } from '@composio/typesafe';
91
92 const provider = new TypesafeProvider();
93 const composio = new Composio({ provider });
94 const userId = 'example-user';
95 const username = 'pg';
96 const request = `Look up the Hacker News user '${username}'`;
97 const knownArguments: Record<string, Record<string, unknown>> = {
98 HACKERNEWS_GET_USER: { username },
99 };
100
101 async function main() {
102 const toolSet = await composio.tools.get(userId, {
103 tools: [
104 'HACKERNEWS_GET_USER',
105 'HACKERNEWS_GET_TOP_STORIES',
106 'HACKERNEWS_SEARCH_POSTS',
107 ],
108 });
109 const decision = await provider.decide(toolSet, request);
110 console.log(JSON.stringify(decision, null, 2));
111
112 if (decision.kind === 'abstain') {
113 console.log(`No tool call: ${decision.reason}`);
114 return;
115 }
116
117 if (decision.risk !== 'read_only') {
118 console.log(`This example does not execute ${decision.risk} tools.`);
119 return;
120 }
121
122 if (decision.kind === 'partial') {
123 console.log('Arguments to supply:', decision.missing);
124 }
125
126 const result = await provider.execute(userId, decision, {
127 arguments: knownArguments[decision.tool] ?? {},
128 });
129 console.log(result.data);
130 }
131
132 main().catch(error => {
133 console.error(error);
134 process.exitCode = 1;
135 });
136 ```
137
138 Run the script with Node.js:
139
140 ```bash
141 node select-tool.ts
142 ```
143
144 </Tab>
145 </Tabs>
146
147 The script prints the decision, the missing argument paths, and the Hacker News profile. A decision for this request typically has `kind: 'partial'`, `tool: 'HACKERNEWS_GET_USER'`, and `missing: [['username']]`. Confidence scores depend on the request and model version.
148
149 The partial call is expected: Jev can select the tool but does not generate the username. `execute` combines the arguments from Jev with the values your code supplies. Caller values take precedence. If a required value is still missing, execution raises `TypesafeIncompleteDecisionError` before calling the tool.
150
151 When you adapt this script, collect missing values from your application or ask the user for them. The `suggestions` field can contain uncertain model answers; treat those as candidates to review, not confirmed input.
152
153 ## Try an abstention
154
155 Change `request` to `Explain what Hacker News is without using any tools`, then run the script again. If Jev returns `abstain`, the script prints its reason and exits without executing. The model may also abstain when no tool fits or confidence is too low.
156
157 Keep API failures separate from abstentions. A timeout or invalid TypeSafe key raises an error, so it appears as a failed run instead of "No tool call."
158
159 ## Shortlist tools for another provider
160
161 If you already use an LLM to choose arguments, ask Jev to narrow its tool list first. This separate script ranks up to 50 Hacker News tools, keeps three, and converts them to OpenAI's tool format. It does not call OpenAI or execute a tool.
162
163 Install the OpenAI provider alongside the packages above:
164
165 {/* code-example: no-api reason="TypeSafe provider shortlists tools client-side for an OpenAI provider" */}
166 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
167 <Tab value="Python">
168
169 <PackageInstall packages="composio-openai" ecosystem="python" />
170
171 ```python title="shortlist-tools.py"
172 from composio import Composio
173 from composio_openai import OpenAIProvider
174 from composio_typesafe import TypesafeProvider
175
176 typesafe = TypesafeProvider()
177 composio = Composio(provider=OpenAIProvider())
178 request = "What are the top stories on Hacker News right now?"
179
180 raw = composio.tools.get_raw_composio_tools(toolkits=["hackernews"], limit=50)
181 shortlist = typesafe.shortlist_tools(raw, request, k=3)
182 tools = composio.tools.get(
183 user_id="example-user",
184 tools=[tool.slug for tool in shortlist["tools"]],
185 )
186 print(shortlist["scores"])
187 print(f"Prepared {len(tools)} tools for OpenAI")
188 ```
189
190 ```bash
191 python shortlist-tools.py
192 ```
193
194 </Tab>
195 <Tab value="TypeScript">
196
197 <PackageInstall packages="@composio/openai" />
198
199 ```typescript title="shortlist-tools.ts"
200 import { Composio } from '@composio/core';
201 import { OpenAIProvider } from '@composio/openai';
202 import { TypesafeProvider } from '@composio/typesafe';
203
204 const typesafe = new TypesafeProvider();
205 const composio = new Composio({ provider: new OpenAIProvider() });
206 const request = 'What are the top stories on Hacker News right now?';
207
208 const raw = await composio.tools.getRawComposioTools({
209 toolkits: ['hackernews'],
210 limit: 50,
211 });
212 const shortlist = await typesafe.shortlistTools(raw, request, { k: 3 });
213 const tools = await composio.tools.get('example-user', {
214 tools: shortlist.tools.map(tool => tool.slug),
215 });
216 console.log(shortlist.scores);
217 console.log(`Prepared ${tools.length} tools for OpenAI`);
218 ```
219
220 ```bash
221 node shortlist-tools.ts
222 ```
223
224 </Tab>
225 </Tabs>
226
227 Pass the resulting `tools` to your [OpenAI agent](/docs/providers/openai). Shortlisting selects candidates; your agent still chooses which candidate to call and supplies its arguments.