Skip to Content

Connect Your Agent

What your agent's API and test environment need so Shade can red-team the whole agent, not only its model

This page is for the engineers who own an AI agent and its runtime. It explains what Shade needs to test the agent end to end, with its real tools, guardrails and environment.

You run the agent on your own infrastructure and expose an HTTP API for it. Gray Swan builds the Shade connection that calls the API. Your API doesn't need a specific shape: this page lists the operations Shade needs, and if your agent already has an API that does the same things, Gray Swan adapts Shade to it.

For a quick test of a model, or of an agent that accepts OpenAI-compatible chat completion requests, you don't need this page. See How Shade reaches your agent.

How Shade tests an agent

For each scenario, Shade repeats these steps:

  1. An attacker model writes an attack.
  2. Shade places the attack: in the user's message for a direct attack, or in a file, an email or a web page that a tool returns for an indirect prompt injection attack.
  3. Your agent runs as it does in production, against that input.
  4. Shade collects what happened, and judge models decide whether the attack worked.

Shade keeps the attacks that make progress and tries variations of them. It runs many attempts at the same time, so each attempt needs its own isolated copy of the agent and its data.

Choose a test mode

ModeWhat Shade doesWhat you provideTrade-off
Transcript replayPlaces attacks in real or synthetic transcripts and sends the conversation to your agent's model directly.Transcripts with tool calls and outputs, the system prompt, the tool definitions and access to the model.The fastest start, with no integration to build. Your runtime, tools and guardrails don't run, and Shade sees only the model's next step.
Live run from the startStarts a fresh agent and plays the user and the attacker.An API with the operations below.The most realistic, and needed to test guardrails, sandboxes and side effects. The slowest, and uses the most tokens.
Live run from a checkpointResumes your agent from a saved conversation that ends with an attack in a tool response or a user turn.The same API, with checkpoints or Send transcript, plus the saved conversations.Cheaper than a live run from the start, and the whole runtime still runs. You collect the conversations first.

Start with transcript replay if you want early results while you build the integration. For formal scans, use a mix of live runs from the start and from checkpoints.

For transcript replay, you don't need the rest of this page. Send Gray Swan the transcripts, the system prompt and the tool definitions, and tell us how to reach the agent's model.

Prepare a test environment

  • Run the agent in a dedicated test environment. Don't connect Shade to production.
  • Keep the agent the same as in production: system prompt, model, tool definitions, skills, guardrails and settings.
  • Stub or block every action with an effect outside the test environment, such as sending email, posting messages, payments or deployments.
  • Expose the agent's endpoints over HTTPS. Shade calls them from Gray Swan's cloud, so allowlist Gray Swan's egress IP address. See Prepare the target for the address.
  • Authenticate every request. A bearer token is simplest. A signed JWT behind an identity-aware proxy also works, such as Google IAP with a service account you issue to Gray Swan.

Operations your API needs

The names and paths are examples. Yours can differ.

OperationExampleRequired?What it does
Create sessionPOST /sessionsRequiredStarts a clean, isolated agent instance. Accepts an optional system prompt, scenario files or seed data, and a checkpoint to restore. Returns a session ID.
Send turn or Send transcriptPOST /sessions/{id}/turns with one user message, or POST /sessions/{id}/transcript with a whole conversationRequiredRuns the agent to the end of its turn and returns the new messages and a status. See Rewinding to an earlier turn.
CheckpointPOST /sessions/{id}/checkpoint, or a flag on Send turnStrongly recommendedSaves the agent and environment state after a turn. Returns a checkpoint ID that Create session can restore, more than once.
Run commandPOST /sessions/{id}/execRecommendedRuns a command in the agent's environment, from outside the agent, and returns its output. Shade uses it to run a grading check after a turn. The agent must not see it.
Get stateGET /sessions/{id}/stateRecommendedReturns a snapshot of the environment, such as files, records or actions taken, and ideally the full conversation as the model sees it.
Delete sessionDELETE /sessions/{id}RequiredTears the instance down. Checkpoints stay after the delete.

Turns can take minutes. A long synchronous call is fine, and so is an asynchronous call with a status endpoint that Shade polls.

A single-turn agent, such as a pull request reviewer, can do all of this in one request. Shade sends one request for each attempt, with the attack already placed in the input, and the agent returns its result and transcript.

Rewinding to an earlier turn

Shade often goes back to an earlier point in a conversation to try a different attack. Your API can support this in one of three ways:

  • Checkpoint. Shade restores the agent and its environment from the end of an earlier turn. Many attempts branch from the same turn without replaying it. This is the fastest and most faithful option.
  • Send transcript. Shade sends the earlier conversation, which it can edit, and the agent continues from its last message. This lets Shade resume just after a tool result that carries an attack. A transcript restores only the conversation, not files or memory, so if earlier tool calls changed the environment, support checkpoints as well. Many agents can't continue a conversation they didn't produce. If yours can't, use Send turn.
  • Neither. Shade still works. It creates a fresh session and replays the earlier turns with Send turn. Scans take longer and cost more, and the agent may answer the replayed turns differently.

Other requirements

  • Concurrent sessions. Support several sessions at the same time, and tell Gray Swan the limit. When you're full, return a clear "busy" response to Create session, such as HTTP 429.
  • Messages as the model sees them. Return messages after your own truncation and formatting. Any common format works: OpenAI, Anthropic or your own event log.
  • Guardrail decisions. Include them in the messages: classifier verdicts, approval prompts and sandbox denials.
  • Agent version. Report the build, prompt revision and model with each session.
  • System prompt and tool definitions. Share them with Gray Swan, in your scoping document or through an endpoint. Shade uses them to brief its attacker.

Evidence Shade uses to judge

The operations above give Shade the evidence its judges need. Which evidence matters depends on the scenario.

EvidenceUsed to
TranscriptConfirm the attack reached the model, and judge what the agent said and which tools it called with which arguments.
Final outputJudge the result the user would see, such as the last message or an output file.
Status and guardrail decisionsCount defended attempts and see which guardrail acted.
Environment stateJudge changes that don't show in the transcript, such as a changed file or a new scheduled job.

Next steps

  1. Tell your Gray Swan team which of these operations your agent already supports, and send your API documentation.
  2. Gray Swan builds the Shade connection and runs a smoke test with you: one run without an attack, then one with a harmless marker attack.
  3. Gray Swan drafts scenarios from your threat model, and your team reviews them.
  4. Your team starts scans from the Gray Swan Platform. See How Shade Works for what happens during a scan.

On this page