Managing agents

By the end of this page you will know how to add agents to a deployment, control which version each one serves, test them against the live deployment, and expose an AI Agent for agent-to-agent access.

Prerequisites

• Admin role.
• A deployment with at least one agent, or an agent with a PRODUCTION version ready to add.

The Agents tab

Open a deployment and select Agents to see every agent inside it. Each agent shows its type (AI Agent or Task Agent), status, version behavior, rate limit, and any schedule.

Throughout this page the examples use a deployment with two agents:

• Sales Ingestor — a Task Agent that ingests sales data on a schedule.
• Revenue Analyst — an AI Agent that answers questions about that data.

Adding and removing agents

Click Deploy Agent to add more agents to this deployment — the deploy wizard opens with this deployment preselected. Only agents that have a PRODUCTION version appear in the picker.

To remove an agent, open its menu and choose Remove. It stops serving immediately; the rest of the deployment keeps running.

Version behavior

Each agent runs one of two version strategies:

• Latest production — the agent always serves its newest published version. When you promote a new version, the deployment switches to it automatically.
• Pinned — the agent stays on a specific version until you change the pin, even if you publish newer versions.

Set this per agent from the agent’s inline Settings, along with its rate limit (requests per minute).

Testing an agent

The Test action opens a console that sends real requests to the agent on the live deployment — the same path your integrations use. It’s the fastest way to confirm a deployed agent behaves as expected.

Test the AI Agent

Open Test on the Revenue Analyst and ask a question it should answer from the deployed data, for example What was total revenue on 2026-07-20?. The console streams the reply back.

Test the Task Agent

Open Test on the Sales Ingestor and send the request. A Task Agent’s run is asynchronous: the call returns a run id right away while the graph runs in the background. To see its status and output, open the run in Executions — or call the run-details endpoint with the run id (see API access).

Agent endpoints

Each deployed agent gets a set of HTTP endpoints under the deployment’s base URL. Open an agent’s Endpoints to see its exact URLs, with copy buttons. The set depends on the agent type:

• AI Agents expose run, streaming, and conversation endpoints — plus the A2A JSON-RPC endpoint and agent cards when A2A is enabled.
• Task Agents expose run and run-history endpoints.

A2A rows are grouped under an A2A Protocol heading with the protocol version. Rows marked legacy are the deprecated REST task endpoints — new integrations should use POST /a2a.

To actually call these endpoints you need an API key. See API access.

Agent-to-agent (A2A) access

A2A lets other agents and external systems call an AI Agent in this deployment as if it were a tool. Turn on A2A Protocol in the agent’s settings (available for AI Agents).

qRaptor implements the standard A2A protocol  over JSON-RPC 2.0 — the message/send generation, covering A2A 0.2.x and 0.3.0 — so any compliant client works, including agent frameworks such as Google ADK and LangGraph.

When A2A is enabled:

• The agent publishes a discovery document (an agent card) at a public well-known URL, so other systems can find its capabilities. Both card locations are served: agent-card.json for A2A 0.3.0+ clients and agent.json for 0.2.x.
• It exposes a JSON-RPC endpoint at /agents/{id}/a2a accepting message/send, message/stream, tasks/get and tasks/cancel (these require an API key with the a2a scope).
• The settings panel shows the negotiated protocol version with copy buttons for the endpoint and card URLs — the two values an integrator needs.
• The deployment shows an A2A Discovery banner listing the public agent-catalog URL and how many agents have A2A enabled.

Testing discovery

Click Test Discovery on the banner to fetch the deployment’s agent catalog. The catalog and the per-agent cards are public — no API key needed — so this is a quick way to confirm your agent advertises itself correctly. The response lists each A2A-enabled agent and its card.

Testing A2A calls

Open Test on an A2A-enabled agent and pick the POST /a2a endpoint. A Method selector appears — choose message/send, message/stream, tasks/get or tasks/cancel and the request body is filled with a matching JSON-RPC envelope.

Two things to know when testing:

• A2A tests need an a2a-scoped key, not the invoke key used for the other endpoints.
• JSON-RPC always answers HTTP 200, even for protocol errors. The console therefore shows a second badge derived from the response body — the task state (completed, working, input-required) on success, or the JSON-RPC error code on failure.

If message/send returns state working, the agent is still running: the response carries a task id, and Use this task id → switches the console to tasks/get so you can poll for the result.

Common issues

• An agent isn’t in the picker — it needs a PRODUCTION version. Publish it first.
• The deployment serves old behavior — the agent is likely pinned. Switch it to latest production, or update the pin.
• Test returns 401 — the console calls the live deployment; make sure the deployment’s authentication is configured. See API access.