Tools

Often you don't want your agent to have every tool of a connector. For instance, your support agent needs to read issues, not search all your code. This page is about the tools that connectors bring. Your own functions are in Tool calling and dispatch.

See a connection's tools

getstream agents connections tools company

TOOL                               READS ONLY  NEEDS SCOPES
actions_get                        yes
actions_list                       yes
actions_run_trigger                no
add_comment_to_pending_review      no
add_issue_comment                  no
add_reply_to_pull_request_comment  no
assign_copilot_to_issue            no
create_branch                      no
create_or_update_file              no
create_pull_request                no
...

The CLI validates the connection first, so the list is what the provider offers now. Each row is one tool: READS ONLY is yes for a tool the connector marks as read-only, and NEEDS SCOPES names the scopes a call of the tool needs. Here it is empty for every tool. The output is cut to ten rows.

A connection that needs a reconnect, new scopes or an approval prints why and fails:

Error: connection company: The provider rejected the stored token or key; replace it with PUT /v1/agents/connections/{id}/credentials

To replace the token or key, save it again as in Save the token.

The command takes only an app connection, by its label or its id.

In the Dashboard:

See what the agent gets

getstream agents tools support

CONNECTOR  NAME    ACCOUNT                 GRANT      REQUIRED  SANDBOX
github     github  App connection company  All tools  no        no

It shows each connector as stored now: as last synced, plus any change saved in the Dashboard since. GRANT reads All tools when every tool is offered, and otherwise the tool names or patterns as written in agent.yaml. ACCOUNT reads Each user's own for a connector with no connection.

In the Dashboard, open the agent and go to its Tools tab. Each row under Connectors shows the same: whose account, such as App connection company, and the grant, such as All tools or Tools matching list_issues, get_*.

Offer only some tools

tools names the tools to offer, or a pattern such as get_*:

name: support
mode: text
llm: llm-fast
connectors:
  - name: github
    connection: company
    tools: [list_issues, get_*] # list_issues, and every tool whose name starts with get_

Sync the agent, then check the new grant:

getstream agents sync support
getstream agents tools support

CONNECTOR  NAME    ACCOUNT                 GRANT               REQUIRED  SANDBOX
github     github  App connection company  list_issues, get_*  no        no

Leave tools out to offer every tool. The agent then stores the pattern *, which is what the Dashboard shows as "All tools".

In the Dashboard:

Give a connector another name

The model sees each tool as <name>__<tool>. Set connector when that name should differ from the connector id:

connectors:
  - name: code # the model sees code__list_issues
    connector: github
    connection: company

In the Dashboard, it is the Name field of Edit. The NAME column of getstream agents tools support shows it.

Require a connector

By default a connector is optional: when its connection is missing or not connected, the session goes on without its tools. required: true refuses to open the session instead:

connectors:
  - name: github
    connection: company
    required: true

A test with a connection that is not connected yet stops before the conversation:

getstream agents test support

Error: cannot start a conversation with support: session: required connector "github" cannot be used: not_connected: the connection is not connected

In the Dashboard, it is the Required checkbox of Edit. The REQUIRED column of getstream agents tools support shows yes.

Where to manage connectors

If agent.yaml has no connectors key, manage them in the Dashboard.

When someone changed the connectors in the Dashboard since your last sync, getstream agents sync stops and shows the change. Copy the change into agent.yaml and sync again, or sync with --overwrite to replace it.

agent.yaml keys

Each entry under connectors takes these keys:

A name alone, such as - linear, is the same as name: linear.

When the agent syncs, a connector whose connection the app doesn't have is left out with a warning, and the rest of the agent syncs. With required: true, the sync fails instead. Leaving connectors out of agent.yaml keeps what is already stored, and an empty list removes it.

Going further