
Each local area page used to take us half a day to create and optimize.
With SEOmatic, we can create hundreds of pages in the same time, which helps our clients make the best use of their budget.
It's transformed how we deliver scalable SEO solutions.
Will Hawkins
Marketing Director, Digi-Business UK
Agents read your Search Console data, do the work, and prove what actually moved. You decide what ships.
14-Day Trial for $1, credited to your first payment.
SEOmatic speaks the Agent2Agent (A2A) protocol. Any A2A client can send it a question about your website and get the answer back as a task, from your own Search Console data and live page checks. It reads only and never changes your site.
Each message is one question, answered for the SEOmatic workspace your API key or sign-in belongs to. The agent has three skills:
| Skill | What it does |
|---|---|
| Answer SEO questions from Search Console | One plain-language question about your site, answered from its Search Console data (clicks, impressions, position, top queries and pages, gains and losses) with the numbers behind the answer. Needs Search Console connected in SEOmatic. |
| Audit a page | Checks one page of your site: titles, descriptions, headings, structured data, whether Google can crawl and index it, and page speed, then names the fixes that matter most. |
| Read the SEO task board | Lists the fixes waiting for approval, in progress or live, and explains any one of them. Approving a fix stays in SEOmatic or the REST API. |
Point your A2A client at the Agent Card. It lists the endpoint, the skills and the sign-in options.
https://app.seomatic.ai/.well-known/agent-card.jsonThe endpoint is POST https://app.seomatic.ai/api/a2a (JSON-RPC). Send the header A2A-Version: 1.0 for A2A 1.0. Without it, requests and the Agent Card use A2A 0.3.
chat:ask scope, from Settings > AI Agents > API Keys, sent as Authorization: Bearer smk_live_.... See create and manage API keys.chat:ask scope (authorization code with PKCE, or, with the A2A 1.0 Agent Card, the device flow for clients without a browser). The Agent Card links the authorization server.Send the question as a text part. Questions are up to 2,000 characters, and the answer is plain text.
curl -X POST "https://app.seomatic.ai/api/a2a" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-H "A2A-Version: 1.0" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "SendMessage",
"params": {
"message": {
"messageId": "msg-1",
"role": "ROLE_USER",
"parts": [{ "text": "Which pages lost the most clicks in the last 28 days?" }]
}
}
}'The result is a task. When it is TASK_STATE_COMPLETED, the answer is in its answer artifact. A workspace out of questions or credits gets TASK_STATE_REJECTED with a message that says what to do. A question that could not be answered ends TASK_STATE_FAILED and is not charged.
Each task answers one question. For a follow-up, send a new message without taskId. Keep the same contextId to group them.
Some questions take longer than your client wants to wait. Set configuration.returnImmediately: true (A2A 1.0) or configuration.blocking: false (A2A 0.3). The task comes back at once as TASK_STATE_WORKING. Read it with GetTask until it completes. Tasks are kept for 24 hours.
| A2A 1.0 | A2A 0.3 | What it does |
|---|---|---|
| SendMessage | message/send | Ask one question. Blocking by default: the answer comes back in the task. |
| GetTask | tasks/get | Read a task, for example one you started without waiting. |
| ListTasks | (v1.0 only) | Your workspace's recent tasks, newest first, up to 100. |
| CancelTask | tasks/cancel | A question that has started cannot be stopped: it answers TaskNotCancelableError. |
The A2A agent uses the same engine as POST /api/v1/ask, with the same limits. One message is one question: free workspaces use their monthly question allowance, paid workspaces use AI credits, and a workspace without a plan can pay with prepaid credits. A paid answer carries the X-SEOmatic-Cost and X-SEOmatic-Balance headers when it was paid from prepaid credits, and X-SEOmatic-Questions-Remaining on a free workspace.