Skip to content

Tools and the tool gateway#

An agent's tools are reached only through the tool gateway on the machine its run is on. The gateway knows the run by its workload token, decides each call with the run's own policy, adds the credential, forwards what is allowed and records every step. This page explains the kinds of tools, what a call goes through, and what is kept.

The kinds of tools#

Kind What the agent calls What is decided
MCP (mcp) An MCP server over streamable HTTP. The agent sees it as an MCP server on the gateway. Each tools/call, by the tool's name and arguments. tools/list answers show only the tools the policy would allow.
HTTP (http) A plain HTTP API at a base URL (https://api.github.com). Each request: its method, host, path and query.
Web (web) Any public http(s):// page, each request naming it. No URL, no credential. Each request, like an HTTP tool's, recorded with its full URL.
The provider's tools Tools the model's provider runs on its side: Anthropic's web search, web fetch and code execution, OpenAI's web search and code interpreter. Each one offered in a model request. Not permitted: removed from the request; the model goes on without it.

Connections in the console are ready-made tools for common services — GitHub (MCP or REST), Slack, Notion, Linear, Jira, Confluence, Gmail, Google Drive, Google Calendar, Brave Search, Tavily, Exa, Sentry, Stripe, and Web browsing — each with its URL, how its credential is sent, and three access levels written as policy for you: read only, read and write, writes need approval. See Add tools and connections.

The model goes through it too#

A provider's model is reached at the gateway too: the run's client is given the gateway's address and the workload token as its "API key"; the gateway swaps it for the provider's key, read from your credential on the machine, and counts the tokens of every answer. An Eos deployment is reached the same way, with no key. Model calls are not decided by Cedar; they are limited by the budgets and may be sent to another model by routing rules.

What a call goes through#

sequenceDiagram
  participant A as Agent (sandbox)
  participant G as Tool gateway (machine)
  participant S as Tool (GitHub, MCP server, page)
  A->>G: request + workload token
  G->>G: who: the run, its agent and version
  G->>G: decide: tool policy + guardrails
  alt permitted
    G->>S: request + credential (from your store)
    S-->>G: answer
    G-->>A: answer
  else forbidden or not permitted
    G-->>A: 403 TOOL_CALL_DENIED, with the rule and reason
  else permitted only with @approval
    G->>G: hold the call, ask for an approval
    G-->>A: answer once approved, or the refusal
  end
  G->>G: trace the step
  1. Who. The token says which run, agent and version calls. A token presented from another address than the run's is refused.
  2. What. The call becomes a Cedar request: the principal (the agent version, the run, who started it), the action (tools/call, http, model/server_tool), the resource (the tool, or the URL) and the context (time, arguments, query). See Cedar reference.
  3. Decide. Nothing is allowed unless a permit matches; any matching forbid wins. A call permitted only by rules marked @approval is held for a person (Approvals).
  4. Forward. The gateway adds the credential — a static key, or an OAuth access token it obtains from a refresh token — and the tool's fixed headers, and forwards the request. The agent never holds either.
  5. Record. The step goes into the run's trace: the tool, the decision, the rules that decided, and bounded arguments.

The web tool connects only to public addresses: never the machine itself, private, link-local or CGNAT ranges, nor the cluster's own names; it does not follow redirects (the agent may ask for the new page, which is decided again) and cuts answers at 5 MiB.

What is kept, and where#

Record Where What
Trace The run's machine Each model call (model, route, tokens, cost) and each tool call (target, decision, rules, arguments shortened to 2 KiB, values that look like keys hidden).
Activity The run's machine Everything that left the run: requests with their URL, connections, DNS lookups, allowed or refused, by the gateway, OpenShell or the machine's firewall.
Counts Astralyx Calls, decisions and refusals per run, what it spent, events such as call denied.
Receipt Astralyx (digests only) See Receipts.

Machines keep traces and activity for 7 days after the run is gone from them by default; a workspace admin changes it under Retention (see Evidence packs and retention).

Credentials#

A tool's credential, and a provider's key, are credentials of the workspace: references to a secret in your own store (Vault, AWS Secrets Manager, Google Secret Manager, Azure Key Vault), fetched by your machine. Astralyx never holds their values. The agent never sees them, except the ones you expose deliberately as environment variables.