Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.portkey.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

Introduction

The Quickstart 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);
});

Further reading

Quickstart

Get started with the Agent Gateway by registering your first agent.

Agent Registry

Manage your agent integrations and control access to agents and their skills.

Agent Servers

Learn how virtual agent servers work and how to host your own.
Last modified on April 29, 2026