HTTP Tools & OAuth

A generic shell or curl tool lets the LLM guess flags, guess endpoints, and improvise auth headers. HTTP tools take a different path: the agent declares the endpoint ahead of time, with a typed parameter schema and a body template. The runtime handles auth, labels, and UI.

This is how a Rush agent hits the user's real Gmail inbox or real Twitter account — not a sandbox, not scraping, not an API key in an env var. The user connects their account once; every agent that needs it picks up the token.

Add an http_tools block to agent.yaml. Each key is the tool name the LLM will see. Here is the twitter_post_tweet tool lifted directly from agents/content-writer/agent.yaml:

http_tools:
  twitter_post_tweet:
    description: "Post a tweet to Twitter/X"
    endpoint: /api/v1/twitter/tweets
    method: POST
    auth: bearer
    twitter_token: true
    params:
      text:
        type: string
        in: body
        description: "The tweet text (max 280 characters)"
        required: true
      reply_to:
        type: string
        in: body
        description: "Optional tweet ID to reply to"
        required: false

When the LLM decides to post a tweet, the runtime builds the request, injects the user's Rush session token and their Twitter OAuth token, fires it at the proxy, and returns the parsed response.

Full field list for HTTPToolSpec (source: harness/agent/types.go):

The providers below have both a header injection hook in createHTTPToolFromSpec and a server-side handler in prix/api/src/:

Google scopes (gmail, calendar, contacts, docs) are enforced per-tool. If a tool declares google_scopes: [gmail] and the user hasn't granted the Gmail scope, the tool is filtered out at build time — the LLM never sees it.

When the agent calls an HTTP tool, the runtime reads ~/.rush/user.yaml, resolves the two tokens the tool needs, and injects them as headers before the request leaves the machine. The proxy then unpacks those headers and forwards to the upstream API.

The session token (Authorization: Bearer) gates access to the proxy. The service-specific header (X-Twitter-Access-Token, X-Google-Access-Token, etc.) is what the proxy uses to call the upstream API on the user's behalf. Two tokens, one round-trip.

body_template uses Go's text/template syntax. Parameters from params are available by name.

body_template: '{"text": "{{text}}"}'

body_template: '{
  "text": "{{text}}"
  {{if reply_to}}, "reply_to": "{{reply_to}}"{{end}}
  {{if media_ids}}, "media_ids": {{media_ids}}{{end}}
}'

body_template: |
  {
    "to": "{{to}}",
    "subject": "{{subject}}",
    "body": "{{body}}"
    {{if cc}}, "cc": "{{cc}}"{{end}}
    {{if bcc}}, "bcc": "{{bcc}}"{{end}}
  }

APIs often return verbose JSON the LLM doesn't need. Set response_format: toon to convert uniform arrays into a compact tabular form — same data, a fraction of the tokens:

twitter_get_followers:
  description: "Get a sample of the user's Twitter followers"
  endpoint: /api/v1/twitter/followers
  method: GET
  auth: bearer
  twitter_token: true
  response_format: toon

For larger reshaping, use an async config or post-process inside a subagent.

When a user installs an agent that declares twitter_token: true, Rush checks ~/.rush/user.yaml. If Twitter isn't connected, the app prompts for OAuth before the agent runs. Once connected, every agent on that machine that needs a Twitter token picks it up automatically — no per-agent credentials, no env vars, no re-auth.

All tokens live in ~/.rush/user.yaml (mode 0600) under service-specific keys (session, google, twitter, slack). See Account & Tokens for storage details.

Five edits to extend HTTP tools with a new provider. The example below adds Slack; swap names accordingly.

type AgentBuilder struct {
    slackAccessToken string
}

func (b *AgentBuilder) WithSlackAccessToken(token string) *AgentBuilder {
    b.slackAccessToken = token
    return b
}

type HTTPToolSpec struct {
    SlackToken bool `json:"slack_token,omitempty" yaml:"slack_token,omitempty"`
}

if spec.SlackToken && b.slackAccessToken != "" {
    httpTool.AddHeader("X-Slack-Token", b.slackAccessToken)
}

if slackToken := GetSlackAccessToken(); slackToken != "" {
    builder = builder.WithSlackAccessToken(slackToken)
}

http_tools:
  slack_post_message:
    description: "Post a message to a Slack channel"
    endpoint: /api/v1/slack/chat.postMessage
    method: POST
    auth: bearer
    slack_token: true
    params:
      channel:
        type: string
        required: true
      text:
        type: string
        required: true

Minimal agent with three Twitter HTTP tools — post a tweet, read the user's recent tweets, read their followers. This is a stripped-down version of agents/content-writer/agent.yaml:

name: twitter-poster
version: 1.0.0
description: Draft and post tweets with context from the user's timeline

prompt: |
  You help the user post tweets to their Twitter/X account.
  Before drafting, read their recent tweets with twitter_get_my_tweets
  to match their voice. Confirm the draft before calling twitter_post_tweet.

tools:
  - name: web_search

http_tools:
  twitter_post_tweet:
    description: "Post a tweet to Twitter/X"
    endpoint: /api/v1/twitter/tweets
    method: POST
    auth: bearer
    twitter_token: true
    params:
      text:
        type: string
        in: body
        description: "The tweet text (max 280 characters)"
        required: true
      reply_to:
        type: string
        in: body
        description: "Optional tweet ID to reply to"
        required: false

  twitter_get_my_tweets:
    description: "Get the user's recent tweets with engagement metrics"
    endpoint: /api/v1/twitter/tweets/me
    method: GET
    auth: bearer
    twitter_token: true
    params:
      max_results:
        type: integer
        in: query
        description: "Maximum number of tweets (1-100, default 20)"
        required: false

  twitter_get_followers:
    description: "Sample the user's followers to understand the audience"
    endpoint: /api/v1/twitter/followers
    method: GET
    auth: bearer
    twitter_token: true
    params:
      max_results:
        type: integer
        in: query
        required: false

Install it, run rush run twitter-poster, and the runtime takes care of auth, param validation, response parsing, and UI. The LLM sees three neatly typed tools and decides when to use each.