A2A Agents That Call a Website API

A2A agents allow one AI system to discover another, delegate a task, and receive a structured result. When such an agent can call a website API, it becomes part of a real business process: it checks product availability, creates a request, calculates a quote, updates an order status, or collects data for a report.

• A2A - a protocol for communication between agents
• Website API - a controlled access point for data and operations
• Agent Card - a description of agent capabilities and connection details
• Task - a job with a status, result, and execution history
• Core principle - the agent calls approved business operations, not arbitrary URLs

What A2A Is

A2A, or Agent2Agent, connects independent agents. One agent acts as the client, while another publishes its capabilities and performs tasks. They can use different programming languages, models, and infrastructure.

A typical flow looks like this:

1. The client agent receives a user request.
2. It discovers a suitable remote agent through an Agent Card.
3. It creates a task and passes the context.
4. The remote agent calls the website API.
5. The result returns as a message or artifact.

A2A handles agent communication, while the API provides access to website functions. The two layers complement each other but do not replace each other.

Why an Agent Needs a Website API

Without an API, an agent is usually limited to text, document search, or fragile UI automation. An API offers a predictable contract and lets the agent perform actions without imitating clicks.

Useful operations include:

• searching products, services, and content;
• calculating a price, delivery time, or plan;
• creating a lead, request, or order;
• checking payment and delivery status;
• updating a profile or reservation;
• retrieving a personalized result after authorization.

For example, a consulting agent can ask the website agent: "Find an available plan for a team of 20." The website agent checks current rules through the internal API and returns structured options.

Integration Architecture

A practical setup has five parts:

Do not give the model a universal tool such as request(url, method, body). Define narrow functions instead:

search_products(query, filters)
calculate_quote(product_id, quantity)
create_lead(name, contact, consent)
get_order_status(order_id)

This makes permissions, argument validation, testing, and auditing much easier.

Agent Card and Capability Description

An Agent Card helps clients understand which tasks an agent can handle. It normally contains a name, description, URL, supported authentication methods, and a list of skills.

A skill description should be specific. "Works with the website" says very little. "Searches the catalog, calculates a quote, and creates a request after user confirmation" is much more useful.

Do not publish these items in an Agent Card:

• API keys or internal tokens;
• private service addresses;
• details that make authorization bypass easier;
• operations unavailable to external clients.

Authentication and Permissions

The A2A connection and website API call may use different credentials. The agent must prove its own identity, while the API must know on whose behalf an action is performed.

Three common modes are:

1. Service account - suitable for shared data and background operations.
2. Delegated user access - required for orders, profiles, and personal data.
3. Confirmed operation - the agent prepares an action and the user approves it before writing.

Limit permissions by endpoint, HTTP method, user, and data type. Read access to the catalog must not automatically grant permission to change prices or delete orders.

Call Security

The main risks are instruction injection, invalid arguments, data leakage, and duplicate execution.

A minimum security baseline includes:

• validate input against a strict schema;
• allowlist approved operations;
• keep secrets out of prompts and A2A messages;
• use an idempotency key for creation and payment;
• limit call frequency and cost;
• require confirmation for financial and irreversible actions;
• mask personal data and tokens in logs;
• return only necessary response fields to the agent.

Treat text from users and other agents as untrusted input. Even a convincing instruction inside a document must never expand tool permissions.

Synchronous and Long-Running Tasks

Searches and calculations can often return immediately. Imports, large reports, or order processing may take minutes. These operations benefit from task states such as submitted, working, completed, failed, and canceled.

The client can receive updates through event streaming, a webhook, or status polling. Reconnecting must not start the business operation again.

Errors and Observability

An agent needs a clear outcome, not a raw stack trace: the operation is temporarily unavailable, an argument is invalid, access is denied, or confirmation is required. Internal details belong in protected logs.

For diagnostics, record:

• task, session, and user identifiers;
• the called tool name;
• a safe copy of arguments;
• API response code and duration;
• confirmation status;
• agent and tool schema versions.

This helps distinguish a model error from an API, network, or business-rule failure.

Implementation Plan

1. Select one use case with measurable value.
2. Define a narrow API contract and data schemas.
3. Build separate tools instead of universal HTTP access.
4. Add authentication, limits, and audit logs.
5. Publish an Agent Card with accurate skill descriptions.
6. Test errors, retries, cancellation, and malicious input.
7. Start with read-only or draft mode.
8. Allow writes only after reviewing real logs.

Summary

An A2A agent with website API access can connect external AI systems to real business services. A reliable integration is built around narrow tools, strict schemas, limited permissions, confirmations, and auditability, not unlimited model freedom.

Want to connect an A2A agent to your website API - contact me.

Frequently Asked Questions

How is A2A different from a regular REST API?

A REST API describes application operations, while A2A covers agent communication and the task lifecycle. A2A may use REST or another transport, and the agent then accesses the website API through controlled tools.

Do I need A2A if my agent can already call an API?

Not always. A direct API call may be enough for one internal agent. A2A is useful when independent agents need to discover each other, delegate tasks, and exchange results through a shared protocol.

Can I give the agent a universal HTTP client?

Technically yes, but it is risky in production. Narrow functions with an allowlist, schemas, and separate permissions are easier to secure, test, and audit.

How do I prevent duplicate orders?

Use an idempotency key and store the link between the A2A task and the business operation. A repeated request with the same key must return the previous result instead of creating another record.

Which actions require user confirmation?

Require confirmation for payments, publishing, outbound messages, personal-data changes, and other costly or irreversible operations. Search, public-data reads, and draft preparation can usually be automated.