Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 03:37 UTC
| 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. |