Skip to main content

Introduction

The Getting started guide provides a basic example of how to use the Agent Gateway. This guide provides more examples and code snippets to help you get started.

Fetching the agent card

curl --location --request POST 'https://agents.portkey.ai/v1/agent/{agent-slug}/.well-known/agent.json' \
--header 'Content-Type: application/json' \
--header 'x-portkey-api-key: {PORTKEY_API_KEY}'

Invoking the agent

JSON-RPC examples

cURL
curl --location 'https://agents.portkey.ai/v1/agent/{agent-slug}' \
--header 'Content-Type: application/json' \
--header 'x-portkey-api-key: {PORTKEY_API_KEY}' \
--data '{
    "jsonrpc": "2.0",
    "id": "req-1",
    "method": "tasks/send",
    "params": {
        "id": "task-header-1",
        "message": {
            "role": "user",
            "parts": [
                {
                    "type": "text",
                    "text": "echo Hello from header auth"
                }
            ]
        }
    }
}'
python
import asyncio
import json
from uuid import uuid4

import httpx

BASE_URL = "https://agents.portkey.ai/v1/agent/header-based-authentication"
API_KEY = "+/gW5Oclr7Y9z01jEOVBaAfKZxfz"


async def log_httpx_request(request: httpx.Request) -> None:
    try:
        body = request.content.decode("utf-8") if request.content else "<empty>"
    except Exception:
        body = "<streaming or unreadable body>"
    print(f"[httpx] {request.method} {request.url}")
    print(f"[httpx] body: {body}\n")


async def main() -> None:
    print(f"Connecting to A2A agent at {BASE_URL}...")
    message_text = "echo Hello from header auth"
    task_id = f"task-{uuid4().hex[:12]}"
    request_id = f"req-{uuid4().hex[:8]}"
    payload = {
        "jsonrpc": "2.0",
        "id": request_id,
        "method": "tasks/send",
        "params": {
            "id": task_id,
            "message": {
                "role": "user",
                "parts": [
                    {
                        "type": "text",
                        "text": message_text,
                    }
                ],
            },
        },
    }

    async with httpx.AsyncClient(
        base_url=BASE_URL,
        headers={
            "x-portkey-api-key": API_KEY,
            "Content-Type": "application/json",
        },
        event_hooks={"request": [log_httpx_request]},
    ) as httpx_client:
        print(f"Sending task with message: {message_text}")
        response = await httpx_client.post("", json=payload)
        response.raise_for_status()
        print(json.dumps(response.json(), indent=2))


if __name__ == "__main__":
    asyncio.run(main())
JavaScript
const BASE_URL =
  process.env.BASE_URL || "https://agents.portkey.ai/v1/agent/{agent-slug}";
const API_KEY = process.env.API_KEY || "{PORTKEY_API_KEY}";
const MESSAGE_TEXT = process.env.MESSAGE_TEXT || "echo Hello from header auth";

async function main() {
  console.log(`Connecting to A2A agent at ${BASE_URL}...`);
  console.log(`Sending task with message: ${MESSAGE_TEXT}`);

  const payload = {
    jsonrpc: "2.0",
    id: `req-${crypto.randomUUID().slice(0, 8)}`,
    method: "tasks/send",
    params: {
      id: `task-${crypto.randomUUID().slice(0, 12)}`,
      message: {
        role: "user",
        parts: [{ type: "text", text: MESSAGE_TEXT }],
      },
    },
  };

  const response = await fetch(BASE_URL, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-portkey-api-key": API_KEY,
    },
    body: JSON.stringify(payload),
  });

  if (!response.ok) {
    throw new Error(
      `HTTP ${response.status}: ${response.statusText} while calling tasks/send`,
    );
  }

  const result = await response.json();
  console.log(JSON.stringify(result, null, 2));
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});
Last modified on April 20, 2026