Picsha AI A2A Agent

Overview

The Picsha AI API supports the Agent-to-Agent (A2A) protocol, an open standard designed to facilitate communication, collaboration, and task delegation between autonomous AI agents.

While the Model Context Protocol (MCP) connects a single agent directly to data and tools, A2A operates at a higher orchestration layer, enabling disparate agents—built on different frameworks and technologies—to discover Picsha, request information, and delegate tasks using natural language.

By exposing an A2A-compliant interface, your agents can coordinate with Picsha as a team member, asking it to locate assets, update metadata, organize collections, or generate CDN rendering links.

Connection Details

The A2A agent interface is served directly alongside your Picsha AI API server:

Agent Card (Discovery): https://api.picsha.ai/v1/a2a/card (or https://api.picsha.ai/v1/a2a/)
JSON-RPC Endpoint: https://api.picsha.ai/v1/a2a/jsonrpc
Protocol Version: 0.3.0

Authentication

Authentication works identically to the core Picsha AI API. You must include your Picsha API key as a Bearer token in the request headers:

POST /v1/a2a/jsonrpc HTTP/1.1
Host: api.picsha.ai
Authorization: Bearer <YOUR_PICSHA_API_KEY>
Content-Type: application/json

Capabilities & Skills

The Picsha A2A Agent exposes a single high-level skill, manage_assets, which represents its complete set of Digital Asset Management (DAM) operations. Under the hood, the agent runs an autonomous reasoning loop to determine how to execute client requests using the platform's internal tools.

Supported Platform Tools

[!NOTE] A2A vs MCP Toolsets The A2A tool list below focuses on headless orchestration. The MCP tools that exist purely for human-in-the-loop chat UIs (render_asset_preview and poll_render, which stream image bytes into a conversation) are omitted from A2A — peer agents retrieve rendered images via generate_render_url instead.

When a peer agent delegates a task via A2A, the Picsha Agent Executor can orchestrate calls to:

search_assets(query, mode): Standard or hybrid semantic vector search.
get_asset(id): Detailed asset metadata retrieval.
list_recent_assets(limit): Retrieve recently added files.
update_asset(id, tags, metadata): Update tags or custom fields.
delete_asset(id, force?): Moves the asset to the Trash, where it is recoverable for 30 days before automatic permanent deletion. Pass force: true to skip the Trash and permanently delete immediately.
restore_asset(id): Restore a trashed asset to its previous state.
moderate_asset(id, action): Approve or reject an asset pending moderation (sets status to active or rejected).
create_dam_group(name, description, assetIds): Organize files into folders/collections.
link_assets(sourceId, targetId, relationshipType): Relate variations or parent/child assets.
trigger_url_ingest(url, filename, config): Import files from public URLs.
get_presigned_upload_url(filename, contentType): Direct-to-S3 secure uploads.
generate_render_url(id, transformations): Retrieve transformed WebP images on the fly.
reanalyze_asset(id): Re-run the AI analysis pipeline on an asset.
summarize_asset(id): Retrieve the AI text summary of a document asset.
escalate_to_support(subject, headline, message): File a report with the Picsha support team.

Every tool call runs against your organization: the agent resolves its tenant from the API key on the request, and x-external-user-id narrows it to a single end user exactly as it does on the REST API.

Integrating with A2A Clients

Raw JSON-RPC (curl)

A2A is just JSON-RPC 2.0 over HTTPS, so any language or framework can talk to the agent without an SDK. First, discover the agent via its Card (no authentication required):

curl https://api.picsha.ai/v1/a2a/card

Then delegate a task with the standard message/send method:

curl -X POST https://api.picsha.ai/v1/a2a/jsonrpc \
  -H "Authorization: Bearer $PICSHA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "message/send",
    "params": {
      "message": {
        "kind": "message",
        "messageId": "1f4a9f3e-2b6c-4d0e-9a71-c8f2d5b30042",
        "role": "user",
        "parts": [
          { "kind": "text", "text": "Find the 3 most recent pictures of dogs in the collection" }
        ]
      }
    }
  }'

The result is either a completed message (with parts containing the agent's response text) or a task object with an id and status when the execution is long-running.

TypeScript Client Example

To interact with the Picsha A2A agent from your own TypeScript application, install the official SDK:

npm install @a2a-js/sdk

The following example demonstrates how to discover the Picsha A2A Agent using its Card, establish a client connection, and delegate a task to search for media assets:

import { A2AClient } from "@a2a-js/sdk/client";
import { Message } from "@a2a-js/sdk";
import { randomUUID } from "crypto";

async function run() {
    // 1. Establish the A2A client pointing to the Picsha JSON-RPC endpoint
    const client = new A2AClient({
        url: "https://api.picsha.ai/v1/a2a/jsonrpc",
        headers: {
            "Authorization": `Bearer ${process.env.PICSHA_API_KEY}`
        }
    });

    console.log("Sending task to Picsha Agent...");
    
    // 2. Delegate a task using the standard message/send method
    const response = await client.sendMessage({
        message: {
            kind: "message",
            messageId: randomUUID(),
            role: "user",
            parts: [{
                kind: "text",
                text: "Find the 3 most recent pictures of dogs in the collection"
            }]
        }
    });

    if (response.kind === "message") {
        const textResponse = response.parts
            .map(part => part.text)
            .join("\n");
        console.log("Picsha Response:\n", textResponse);
    } else {
        // Returned a Task indicating a long-running execution
        console.log(`Task initiated with ID: ${response.id}. Status: ${response.status}`);
    }
}

run().catch(console.error);

Python Client Example

For Python agent frameworks (CrewAI, LangGraph, AutoGen, and others), use the official a2a-sdk package:

pip install a2a-sdk httpx

import asyncio
import os
from uuid import uuid4

import httpx
from a2a.client import A2ACardResolver, A2AClient
from a2a.types import MessageSendParams, SendMessageRequest

PICSHA_RPC_URL = "https://api.picsha.ai/v1/a2a/jsonrpc"

async def main():
    async with httpx.AsyncClient(
        headers={"Authorization": f"Bearer {os.environ['PICSHA_API_KEY']}"}
    ) as httpx_client:
        # 1. (Optional) Discover the agent's capabilities via its Card
        resolver = A2ACardResolver(
            httpx_client=httpx_client,
            base_url="https://api.picsha.ai",
            agent_card_path="/v1/a2a/card",
        )
        agent_card = await resolver.get_agent_card()
        print(f"Discovered: {agent_card.name} v{agent_card.version}")

        # 2. Create the client and delegate a task
        client = A2AClient(httpx_client=httpx_client, url=PICSHA_RPC_URL)
        request = SendMessageRequest(
            id=str(uuid4()),
            params=MessageSendParams(
                message={
                    "kind": "message",
                    "messageId": uuid4().hex,
                    "role": "user",
                    "parts": [
                        {
                            "kind": "text",
                            "text": "Find the 3 most recent pictures of dogs in the collection",
                        }
                    ],
                }
            ),
        )
        response = await client.send_message(request)
        print(response.model_dump(mode="json", exclude_none=True))

asyncio.run(main())