Shell-powered API Agent

The Shell-powered API Agent blueprint extends the ad-hoc authenticated API pattern by moving all API abilities into a separate installable skillset. Instead of calling API abilities directly as conversational tools, the agent installs the API skillset into its shell environment and then invokes each service as a CLI command.

Why Shell + API?

The direct-ability approach (see the Ad-hoc Authenticated API Agent blueprint) works well for simple request-response interactions: the user asks for something, the agent makes one API call, and returns the result. But many real-world tasks require orchestrating multiple API calls in sequence, filtering and transforming intermediate results, and composing outputs from different services. This is where shell scripting shines.

When API abilities are installed as shell commands, the agent can:

• Chain calls with pipes - fetch GitHub issues, filter by label with grep, count them with wc, and write the result to a file in one pipeline.
• Loop over results - list all Slack channels, then iterate over them to post a message to each one.
• Mix services in scripts - pull data from HubSpot, cross-reference with GitHub, and post a summary to Slack - all in a single bash script.
• Use standard Unix tools - jq for JSON parsing, sort for ordering, awk for field extraction, tee for logging, and everything else in the Unix toolkit.
• Store intermediate results - write API responses to files, process them later, and build cumulative reports.

Architecture: Two Skillsets

The agent has two skillsets with a clear separation of concerns:

1. Core Tools (linked to the bot) - general-purpose abilities the agent always has access to:

   • List Available Skillsets (blueprint/resource/list) - discovers installable skillsets in the blueprint
   • Install Skillset as Shell Command (shell/skillset/install[by-id])
     • loads a skillset into the shell environment as CLI commands
   • Bash (shell/exec) - executes shell commands in the sandbox
   • Read File (shell/read) - reads files from the workspace
   • Write File (shell/write) - writes files to the workspace

2. API Toolkit (installable) - the same fetch/request[with-auth] abilities from the ad-hoc pattern, each linked to its own secret:

   • GitHub API Request - linked to platform/github
   • Slack API Request - linked to platform/slack
   • Linear API Request - linked to platform/linear
   • HubSpot API Request - linked to platform/hubspot

At the start of a conversation the agent only has its core tools. When the user asks for something that requires API access, the agent lists available skillsets, finds the API Toolkit, installs it into the shell environment, and then uses bash to call the API commands.

What Installation Looks Like

After installing the API Toolkit skillset, its abilities become CLI subcommands. The agent can then run commands like:

# List GitHub issues for a repo
api-toolkit github-api-request \
  --method GET \
  --url "https://api.github.com/repos/owner/repo/issues?state=open"

# Post a message to Slack
api-toolkit slack-api-request \
  --method POST \
  --url "https://slack.com/api/chat.postMessage" \
  --contentType "application/json" \
  --body '{"channel":"C01ABC","text":"Hello from the agent"}'

# Chain: get GitHub PRs and count them
api-toolkit github-api-request \
  --method GET \
  --url "https://api.github.com/repos/owner/repo/pulls" \
  | jq length

Each command automatically injects the correct authentication token from its linked secret - the agent never touches credentials directly.

Compared to the Direct-ability Approach

| Aspect | Direct abilities | Shell-installed CLI | |-------------------------|---------------------------|---------------------------| | Invocation | Conversational tool call | Shell command | | Chaining | One call at a time | Pipes, loops, scripts | | Output processing | Model parses response | jq, grep, awk | | Scripting | Not possible | Full bash scripting | | Startup cost | Immediate | One-time install step | | Context window | All abilities always present | Only core tools until install |

Both approaches use the same fetch/request[with-auth] template and the same secrets - the only difference is how the agent invokes them.

Getting Started

1. Configure the secrets for each service (GitHub, Slack, Linear, HubSpot).
2. Deploy the blueprint and start a conversation.
3. Ask the agent to do something that requires API access - it will auto- install the API Toolkit and start scripting.
4. Try multi-step tasks: "List all open GitHub issues labeled 'bug', count them, and post the summary to Slack."

Backstory

Common information about the bot's experience, skills and personality. For more information, see the Backstory documentation.