Agent2Agent (A2A) Server

Gradial’s Agent2Agent (A2A) server exposes Grady through an authenticated JSON-RPC API based on A2A, the open protocol originally introduced by Google. Customer systems can create Gradial tasks, attach source files, monitor progress, answer follow-up questions, request cancellation, and retrieve generated artifacts without opening the Gradial UI for every handoff. Use A2A when your organization has an approval agent, workflow orchestrator, case-management system, or internal automation layer that needs to delegate marketing execution work to Grady and receive structured results back.

Protocol And API Surface

A2A provides the interoperability model for agent collaboration and handoffs. Gradial implements that model as authenticated API endpoints that customers can call from trusted server-side systems. This means you can use the same surface in two ways:

Agent collaboration - Another A2A-capable agent can discover Grady, create a task, continue it, and retrieve artifacts through the protocol.
Programmatic work handoff - A customer-owned service can create Gradial work from an approval workflow, ticketing flow, batch process, or internal application, then poll status and sync the result back to the system of record.

In both cases, Gradial treats the request as a governed task in the customer’s Gradial organization, scoped by the API credential, workspace ID, and environment ID.

What A2A Unlocks

Programmatic task creation - Create Grady work from an authenticated backend service instead of relying on manual UI entry.
External approval workflows - Route an approved brief, copy doc, legal markup, or campaign request into Gradial as a governed task.
Agent-to-agent delegation - Let your internal agent hand work to Grady, then poll until the task is ready for review or needs more input.
File-based review - Send PDFs, Word documents, spreadsheets, presentations, images, CSVs, Markdown, JSON, XML, or DITA files as task context.
Artifact retrieval - Download documents and other generated file outputs from the task’s A2A artifacts array.
Operational tracking - Keep your system of record synchronized with Gradial task IDs, status states, messages, and artifact metadata.

How The Integration Works

Discover Grady’s public agent card.
Authenticate your server-side integration with an external API key or OAuth bearer token.
Discover the Gradial workspace and environment IDs for the customer organization.
Send message/send to create a non-blocking Gradial task.
Poll tasks/get for status, history, pending input, and artifacts.
Send follow-up message/send calls when Grady asks for input or when your system needs to add context.
Download generated file artifacts from signed URLs returned in artifacts.

Gradial maps one A2A task to one Gradial task thread. The A2A taskId returned by Gradial is the thread ID you should store and reuse for polling and follow-up messages.

Endpoints

Use the Gradial app host unless your Gradial team gives you a tenant-specific host.

https://app.gradial.com

Purpose	Method	Path
Agent card discovery	`GET`	`/rest/a2a/.well-known/agent-card.json`
Authenticated JSON-RPC task API	`POST`	`/rest/a2a`

The agent card is public so A2A clients can discover Grady before they have credentials. Task operations are authenticated customer API calls.

Authentication

Most customer integrations call the A2A API from a trusted backend service using a Gradial external API key in the X-API-Key header:

curl -sS "https://app.gradial.com/rest/a2a" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $GRADIAL_API_KEY" \
  -d '{ "jsonrpc": "2.0", "id": "ping", "method": "gradial/tasks/list", "params": { "workspaceId": "workspace_example", "limit": 1 } }'

Organization owners or admins can create external API keys from Developer Settings when external API access is enabled for the organization. If Developer Settings is not available for your rollout, your Gradial representative will provision credentials and exchange them through your approved secure channel.

API keys are scoped to a single Gradial organization for A2A. Store them in your server-side secret manager, rotate them on your normal credential schedule, and do not embed them in browser code or distributed clients.

Gradial can also support OAuth bearer tokens for organizations that have an external OAuth application configured. Your Gradial representative will confirm whether OAuth is part of your onboarding path.

Workspace And Environment IDs

Task creation requires a Gradial workspace ID and environment ID. Discover them before creating the first task:

curl -sS "https://app.gradial.com/api/workspaces?organizationId=org_example" \
  -H "X-API-Key: $GRADIAL_API_KEY"

Use the returned workspaces[].id as metadata.gradial.workspaceId and the returned workspaces[].environments[].id as metadata.gradial.environmentId. Do not send display names in A2A requests. Names can change; IDs are stable.

Create A Task

Gradial supports a fire-and-poll model. message/send creates or continues a task, and tasks/get retrieves status and results.

curl -sS "https://app.gradial.com/rest/a2a" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $GRADIAL_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": "create-1",
    "method": "message/send",
    "params": {
      "message": {
        "kind": "message",
        "messageId": "client-message-1",
        "role": "user",
        "parts": [
          {
            "kind": "text",
            "text": "Review this campaign brief and summarize what is ready for approval."
          }
        ]
      },
      "metadata": {
        "gradial": {
          "workspaceId": "workspace_example",
          "environmentId": "env_example",
          "title": "Campaign brief review"
        }
      }
    }
  }'

Store result.id from the response. Use it as message.taskId in follow-up messages and as params.id in tasks/get. Set message.messageId to a unique client-generated identifier for each new message. If your system retries the exact same message after a network failure, reuse the same messageId so Gradial can treat the retry idempotently. Use a new messageId for each new follow-up message.

File Transfer

Gradial supports A2A file parts by URI. This is the supported path for binary assets and larger documents. Inbound file transfer works like this:

Your system creates a short-lived HTTPS download URL for each file.
Your A2A message includes a normal text instruction part plus one or more kind: "file" parts with file.uri.
Gradial downloads the file server-side, validates size and type, stores it as a Gradial attachment, and persists the user message with those attachments.
Grady uses the attachments as task context in the same way it uses files uploaded through the Gradial UI.

{
  "jsonrpc": "2.0",
  "id": "create-with-file-1",
  "method": "message/send",
  "params": {
    "message": {
      "kind": "message",
      "messageId": "client-message-1",
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "Review the attached approval document and summarize open issues."
        },
        {
          "kind": "file",
          "file": {
            "name": "approval.pdf",
            "mimeType": "application/pdf",
            "uri": "https://customer.example/presigned/approval.pdf"
          }
        }
      ]
    },
    "metadata": {
      "gradial": {
        "workspaceId": "workspace_example",
        "environmentId": "env_example",
        "title": "Approval review"
      }
    }
  }
}

Follow-up messages use the same file shape with message.taskId set to the returned Gradial task ID.

The A2A endpoint is not a multipart upload endpoint. Inline file.bytes is not supported, and binary data should not be placed in the JSON-RPC body.

Why Signed URLs

URI-based file exchange is a standard pattern for moving files between systems without copying long-lived storage credentials between them. The A2A specification includes file exchange where generated artifacts can be returned as URL-based file references, and the same model is widely used across major object storage platforms:

Platform	Reference pattern
A2A Protocol	File exchange with URL-based file references
Amazon S3	Presigned URLs for time-limited object download
Google Cloud Storage	Signed URLs for time-limited access to a specific resource
Azure Storage	Shared access signatures for delegated access
Cloudflare R2	Presigned URLs for temporary access to objects

This pattern keeps the source system in control of the file, the allowed operation, and the expiration time. It also avoids granting Gradial permanent access to the customer’s storage account.

Network And Firewall Guidance

The current file-transfer contract is URI-based: Gradial pulls inbound files from the file.uri you provide, and your system pulls generated file artifacts from signed URLs that Gradial returns. For inbound files, the URL must be reachable from Gradial infrastructure over HTTPS. If your object store, API gateway, or firewall restricts access by source IP, allowlist Gradial’s egress IP addresses before testing. See IP Allowlisting. Use these settings for customer-hosted file URLs:

Requirement	Guidance
Protocol	HTTPS only
Authentication	Prefer a short-lived presigned URL that does not require custom request headers
Expiration	Long enough for Gradial to fetch the file during task creation, but not permanent
Reachability	Public internet route or allowlisted Gradial egress IPs
Redirects	Keep redirects minimal; Gradial follows a limited number of redirects
File names	Include `file.name` when possible so reviewers see a meaningful attachment name
MIME type	Include `file.mimeType` when known; Gradial also checks response headers and file extension

If your security policy requires customer systems to push bytes directly into Gradial storage instead of allowing Gradial to fetch a short-lived URL, raise that during onboarding. That is a different transfer pattern from the current A2A contract and should be scoped with your Gradial team before production rollout.

File Limits

Limit	Current behavior
Max file size	50 MB per file
Max file parts	25 files per message
Request body size	256 KB JSON-RPC body limit
Text part size	20,000 characters per text part
Inline bytes	Not supported
Fetch timeout	Gradial enforces a server-side timeout when fetching `file.uri`

Supported input file types include PDF, Word, Excel, PowerPoint, common image formats, plain text, CSV, Markdown, JSON, XML, and DITA. Executable, HTML, JavaScript, SVG, and script-like extensions are rejected.

Generated Artifacts

When Grady produces downloadable files, tasks/get returns them in the task artifacts array as A2A file parts.

{
  "artifactId": "artifact_file_123",
  "name": "Generated approval document",
  "parts": [
    {
      "kind": "file",
      "file": {
        "name": "Generated approval document",
        "uri": "https://app.gradial.com/signed-artifact-download/..."
      },
      "metadata": {
        "gradial": {
          "artifactId": "artifact_file_123",
          "source": "artifact"
        }
      }
    }
  ]
}

Download file artifacts promptly. Gradial storage artifacts use short-lived signed URLs. If your environment restricts outbound internet access, allow your integration runtime to reach https://app.gradial.com. Non-file artifacts return compact data parts with public metadata such as artifact ID, type, name, status, review status, timestamp, and URL when available.

Poll Status And History

curl -sS "https://app.gradial.com/rest/a2a" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $GRADIAL_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": "get-1",
    "method": "tasks/get",
    "params": {
      "id": "thread_example",
      "historyLength": 10
    }
  }'

Common status states:

State	Meaning
`submitted`	The task exists but has not started active work yet.
`working`	Grady is actively working or a workflow is still running.
`input-required`	Grady needs the caller to answer one or more questions before continuing.
`completed`	No active Gradial workflow is running and the task is ready for review or closed.
`failed`	The task failed.
`canceled`	The task was canceled.

historyLength controls how many visible conversation messages are returned. History does not expose hidden internal reasoning, tool-call IDs, internal tool names, or internal user IDs.

Answer Follow-Up Questions

When Grady needs structured input, the task state becomes input-required and the status message includes a gradial.pendingInput data part. Your client should render that data part rather than parsing a natural-language question from the text. Continue the task with message/send and the existing task ID:

{
  "jsonrpc": "2.0",
  "id": "follow-up-1",
  "method": "message/send",
  "params": {
    "message": {
      "kind": "message",
      "messageId": "client-message-2",
      "taskId": "thread_example",
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "Use the Whats New content fragment model."
        }
      ]
    },
    "configuration": {
      "historyLength": 10
    }
  }
}

Production Readiness Checklist

External API access is enabled for your Gradial organization.
Your integration has an external API key or OAuth app scoped to the correct organization.
Workspace and environment IDs are discovered and stored by ID, not by display name.
Your messageId values are unique per new message, with the same ID reused only for safe retries of the same message.
File URLs are HTTPS, short-lived, and reachable from Gradial egress.
Your firewall allows Gradial to fetch inbound file.uri values, or your rollout has an agreed alternate transfer pattern.
Your integration can reach https://app.gradial.com to poll task status and download artifact URLs.
Your client handles input-required tasks and can send follow-up messages.
Your planned request rate and concurrency have been reviewed with Gradial before production launch.

Troubleshooting

Symptom	Likely cause	What to check
`Unauthorized: API key or OAuth token required`	Missing auth header	Send `X-API-Key` or `Authorization: Bearer` from a server-side integration.
`External API access is not enabled`	Organization feature not enabled	Contact your Gradial representative.
`message/send requires metadata.gradial.workspaceId and metadata.gradial.environmentId`	Missing task context	Discover workspace and environment IDs before task creation.
`A2A file.uri fetch failed`	Gradial cannot reach the URL	Check URL expiration, firewall rules, redirects, and source system logs.
`File exceeds maximum size`	File is over the current limit	Split the input or coordinate a higher-capacity transfer pattern with Gradial.
`Inline file.bytes input is not supported`	Binary data was placed in the JSON body	Use `file.uri` with a short-lived HTTPS URL.

Integrations

Ticketing Systems

Managing Access

Agent2Agent (A2A) Server

Protocol And API Surface

What A2A Unlocks

How The Integration Works

Endpoints

Authentication

Workspace And Environment IDs

Create A Task

File Transfer

Why Signed URLs

Network And Firewall Guidance

File Limits

Generated Artifacts

Poll Status And History

Answer Follow-Up Questions

Production Readiness Checklist

Troubleshooting

​Protocol And API Surface

​What A2A Unlocks

​How The Integration Works

​Endpoints

​Authentication

​Workspace And Environment IDs

​Create A Task

​File Transfer

​Why Signed URLs

​Network And Firewall Guidance

​File Limits

​Generated Artifacts

​Poll Status And History

​Answer Follow-Up Questions

​Production Readiness Checklist

​Troubleshooting

Protocol And API Surface

What A2A Unlocks

How The Integration Works

Endpoints

Authentication

Workspace And Environment IDs

Create A Task

File Transfer

Why Signed URLs

Network And Firewall Guidance

File Limits

Generated Artifacts

Poll Status And History

Answer Follow-Up Questions

Production Readiness Checklist

Troubleshooting