AIGP Resource Names (AGRN)#

Every asset in AgentGP follows a standardized naming convention called AIGP Resource Names (AGRN), inspired by URNs (Uniform Resource Names). AGRNs use a type.kebab-case-name format for consistent identification across APIs, SDKs, and audit logs.

Format & Examples#

Naming Rules#

• All AGRNs are globally unique — no two resources of any type can share the same AGRN.
• Names use lowercase kebab-case (letters, numbers, and hyphens only — no underscores, no double hyphens).
• The prefix (agent., policy., prompt.) identifies the resource type.
• AGRNs are used in the Inject API, SDK calls, audit logs, and agent-to-agent communication.

Template Variable Naming#

All Jinja2 template variables must use lowercase snake_case. The editor validates variable names in real time and shows warnings for non-compliant names.

The Governance Protocol#

AgentGP is a protocol-first AI Governance Agent. It does not act as a gateway or proxy. It follows a Registry & Observer pattern: Worker Agents register with AgentGP, then call it over the Google A2A protocol for prompts, policy validation, lineage, and audit.

Terminology#

The Handshake (sequence)#

Canonical flow from boot to inference and audit. The diagram below is rendered with Mermaid and shows the full handshake: check-in → get_prompt → validate_policy → inference → audit_log.

Check-in (registration)#

Agents must check in at boot by sending their manifest to AgentGP. Use the A2A skill register or POST /api/agents/ping. Unregistered agents should not get access to company data.

Separation of concerns#

Prompts (behavior) – Fetched at runtime via get_prompt. Versioned and approval-controlled. Policies (knowledge) – Validated before use via validate_policy or get_approved_policy; AgentGP logs who pulled what (lineage). Tools (capabilities) – Governed external APIs, data stores, and code sandboxes with types, risk levels, kill-switch, and versioned configuration.

Governance requires all three: versioned prompts + access-controlled policies + governed tools, with a single audit trail.

SDKs#

Integrate AI governance into your agents in minutes. AgentGP provides official SDKs for the languages your team already uses — all with a unified interface so the experience is identical regardless of stack.

Quick integration#

Three lines of code to connect any AI agent to governance:

Authentication#

All SDKs authenticate with an API key issued from the AgentGP dashboard. Pass it as api_key in the constructor or set AGENTGP_API_KEY as an environment variable. The key is sent as Authorization: Bearer <key> on every request and maps to a service account for audit attribution.

Configuration#

agentgp.json manifest#

Every AI agent can maintain a agentgp.json file in its git repository. This manifest declares the agent's identity, governance metadata, and which prompts/policies it needs. On agent startup, it pings AgentGP to register and pull approved prompts and policies.

Why use agentgp.json?#

• GitOps for AI Governance – Your agent's governance config lives in version control alongside your code. Changes are tracked, reviewed, and auditable.
• Self-registering agents – On startup, your agent calls AgentGP with its manifest. AgentGP registers/updates the agent and returns approved prompts, policies, and tool configurations.
• Compliance by default – Declare regulatory scope, data scopes, and PII handling upfront. AgentGP enforces policies based on this metadata.

Manifest schema#

REST API#

API base URL: The UI talks to the FastAPI backend. For local development use http://localhost:8000; in production use your company's AgentGP API URL. Set NEXT_PUBLIC_API_URL (client) and BACKEND_URL (server-side/SSR) so prompts and policies lists load correctly.

Core endpoints#

All mutations and inject support optional audit headers (X-AgentGP-Agent-ID, X-AgentGP-Trace-ID) for lineage tracking.

API Reference (Swagger UI)#

Use the interactive Swagger UI to explore and test all endpoints. You can point it at http://localhost:8000 when running locally or at your deployed API URL (e.g. GCP Cloud Run) when testing in production.

Open API Reference (Swagger UI) →

MCP (Model Context Protocol)#

AgentGP exposes a fully compliant MCP server at /mcp using the official mcp Python SDK with Streamable HTTP transport. Connect Claude Desktop, Cursor, Windsurf, VS Code Copilot, or any MCP-compatible client directly to AgentGP for governed access to prompts, policies, and audit lineage.

MCP is the open standard for connecting AI assistants to external tools and data sources. Instead of building custom integrations, any MCP client can connect to AgentGP and use its governance tools natively.

MCP Tools (22 tools)#

AgentGP exposes 22 governance tools through MCP, organized by category:

Agents#

Organizations#

Policies#

Prompts#

Audit & Lineage#

Dashboard & Reports#

Validation#

Tools that access governed data require three parameters: api_key (your service account key), source_agent (your registered agent ID), and trace_id (unique trace identifier for audit logging).

MCP Setup & Configuration#

Prerequisites#

• AgentGP backend running (locally or deployed)
• A registered service account with an API key
• An agent registered in AgentGP and linked to the prompts/policies it needs access to

Claude Desktop#

Add to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

MCP Usage#

Once connected, the AI assistant has access to all AgentGP governance tools. Ask the assistant to use the AgentGP MCP server to perform governance operations:

A2A protocol#

The Agent2Agent (A2A) Protocol is an open standard (see references below) that enables communication and interoperability between AI agents built on different frameworks and by different vendors. A2A allows agents to discover each other's capabilities, negotiate interaction modalities, manage collaborative tasks, and securely exchange information without accessing each other's internal state or tools.

A2A as the industry standard: The Agent-to-Agent (A2A) protocol is fast becoming the standard for AI agents to discover, communicate, and collaborate across vendors and frameworks. The AgentGP AI Governance Agent is central to this: AgentGP is an AI agent that participates in A2A. It acts as an A2A Server (Remote Agent) so your agents can call it for governance—they discover AgentGP via its Agent Card and invoke skills to get approved policies, validate content, retrieve lineage, or register. AgentGP also communicates with other agents via A2A as a first-class agent, so governance lives inside the same protocol your agents already use.

How A2A URLs work in practice#

• Discovery – Agent A uses the A2A URL of Agent B to read its capabilities (e.g. GET /a2a returns the Agent Card).
• Interaction – Agent A sends a JSON-RPC 2.0 message over HTTP(S) to that URL to initiate a task (e.g. POST /a2a with method and params).
• Real-time updates – For long-running tasks, the A2A server may use Server-Sent Events (SSE) to send updates back to the client. AgentGP currently responds synchronously; SSE may be added for streaming or long-running flows.

Specification & key concepts#

For the full protocol specification and terminology (Agent Card, Task, Message, Part, Artifact, transport over HTTP/JSON-RPC, streaming, security), use the official resources:

• A2A Protocol Specification (Google) – transport, Agent Card structure, RPC methods, data objects.
• Key concepts – A2A Client, A2A Server, Agent Card, Task, Message, Part, Artifact.

Discovery (Agent Card)#

Clients discover AgentGP by fetching its Agent Card. The response is a JSON document describing the agent's name, description, service URL, version, capabilities, and skills.

A2A skills reference#

AgentGP exposes 24 governance skills via A2A (matching the 22 MCP tools plus 2 discovery skills). Discovery: GET /a2a returns the Agent Card (name, url, capabilities, skills). Invocation: POST /a2a with a JSON body containing skillId and input. The A2A protocol is JSON; AgentGP enforces required fields per skill. Documented fields below are the source of truth.

Request envelope (POST /a2a)#

AIGP Pipeline — AgentGP Data Platform#

Every A2A integration, REST API call, MCP tool invocation, and audit log described above produces an AI Governance Proof (AIGP) event. AIGP is the core data that powers AI Governance, Risk & Controls, Compliance, and Regulatory requirements — capturing cryptographic hash proofs, trace IDs, and full audit metadata for every governance action.

AgentGP's Data Platform uses Kappa Architecture to stream AIGP events through Kafka into three independent consumer branches: SKCC batch-inserts into ClickHouse for sub-10ms OLAP analytics and Superset dashboards, SKOC indexes into OpenSearch for full-text search and governance investigation, while SKLC batch-appends to a Data Lakehouse (Apache Iceberg on object store) via Polaris for long-term retention and AI/ML use-cases. PostgreSQL remains the OLTP source of truth for entity data (agents, prompts, policies, orgs).

Enterprise Readiness#

AgentGP is built for production enterprise workloads. The platform includes features for high-availability, secure multi-tenant operation, and compliance at scale.

SSO / OIDC integration#

AgentGP supports enterprise single sign-on via the OpenID Connect (OIDC) protocol. Any standards-compliant identity provider can be configured — including Okta, Auth0, Keycloak, Microsoft Entra ID (Azure AD), and Google Workspace. Multiple SSO providers can be active simultaneously for multi-tenant deployments.

RBAC & permissions#

AgentGP uses a five-tier role-based access control model, scoped per organization. Every API write operation checks the caller's permissions via the RequiresPermission middleware.

Built-in roles:

Permission format: Permissions follow the pattern action:resource. Wildcards are supported:

• * — Full wildcard, matches all permissions.
• read:* — All read operations across all resources.
• *:policies — All operations on policies (read, write, approve).
• write:prompts — Exact match for writing prompts.

Organization scoping: Each user's role is assigned per organization via the user_org_roles table. A user can be an Admin in one org and a Viewer in another. The org is resolved automatically from the request path, query parameter, body, or defaults to the primary organization.