Agent Nebula SecureAgent — Examples and Integration Tests

Build and test standards-based A2A agents locally; then connect them to Agent Nebula for registration, discovery, OAuth-scoped invocation, and policy-controlled access.

This repository is the public, executable starting point for agent-nebula-secureagent. It contains 34 numbered scenarios, grouped by whether they require the hosted Agent Nebula platform. Start with a standalone example; use the platform-integrated examples to exercise the Registry and security services.

What is SecureAgent?

agent-nebula-secureagent is a configuration-driven Python interface for building A2A agents and clients. Application code defines business skills and selects protocols; the underlying Agent Nebula Platform integration uses the official A2A Python SDK for protocol behavior. The security SDK supplies reusable security mechanisms. SecureAgent is not the hosted Registry: local examples do not require an Agent Nebula account.

Application / skills / example clients
                  |
       agent-nebula-secureagent
                  |
        agent-nebula-platform
             /           \
     official A2A SDK   agent-nebula-sdk (security)
                  |
           A2A interfaces
                  |
     optional: Agent Nebula Registry / OAuth / Policy / Explorer

A2A and A2UI

A2A defines Agent Cards, skills, messages, tasks, artifacts, streaming, and interoperable protocol bindings (JSON-RPC, HTTP+JSON, and gRPC where configured). SecureAgent examples use the official A2A SDK instead of implementing a second wire protocol. A2UI v1.0 carries structured, renderer-consumable UI updates over A2A; the A2UI examples cover catalogs, forms, actions, tables, charts, tasks, and streaming. A2UI does not replace A2A transport or authentication.

See configuration, A2UI integration, and the example catalogs.

Configuration-driven development

Each example keeps checked-in templates under config/. make init example-NN resolves templates into an external runtime directory, rather than modifying source configuration or committing secrets.

File / input	Responsibility
config/secureagent.conf	Application/runtime identity, logging, and general runtime settings.
config/a2aserver.conf	A2A listener, TLS settings, Agent Card, supported interfaces, advertised skills, and security schemes.
config/a2aclient.conf (or a2aclient*.conf)	A2A client connection and transport/security settings.
config/nebula.conf (when present)	Agent Nebula Registry connection, trust, and registration behavior.
config/a2ui.conf (when present)	A2UI catalog support and negotiation preferences.
presentation.json (when present)	Example-owned A2UI presentation data/catalog references.
.env (from .env.example)	Shared runtime root, hostname, and external service URLs; not credentials.
examples.json	Authoritative example directory, initialization mode, certificate profile, and runnable processes.

Not every example uses every file. For the exact configuration lifecycle, see configuration and initialization.

A2A authentication and security

The reusable security layer supports the A2A authentication mechanisms demonstrated here: API key, HTTP Bearer, OpenID Connect, mutual TLS, and OAuth 2.0, including combinations of requirements. The examples distinguish advertising a security scheme in an Agent Card from validating credentials at the server. OAuth scopes can restrict individual skills; Agent Nebula integration adds hosted registration and policy-controlled workflows. These are different responsibilities, and neither should be bypassed for a passing test.

Use standalone security examples 10–14 to test local mechanisms, and Agent Nebula OAuth/skill-scope examples 07–08 for platform-integrated flows. Read the security guide for the example coverage and boundaries. The standard ngrok HTTP endpoint is not a replacement for end-to-end client-certificate mTLS; example 13 runs locally.

Install from PyPI

Requires Python 3.12. The package installs SecureAgent, Platform, SDK and their declared Python dependencies. To create an editable workspace containing the examples, configuration templates, scripts and Makefile:

python -m pip install agent-nebula-secureagent-examples
agent-nebula-examples init ./agent-nebula-examples
cd agent-nebula-examples
make install
make env-init
make list

The workspace is copied rather than run inside site-packages, so examples can be edited and their generated runtime files remain outside the installed package. Some examples also require external tools or services (such as uv, make, Node.js, TLS certificates, or an Agent Nebula account). See each scenario's README for prerequisites.

Quick start: no Registry account required

Prerequisites: Python/uv, plus any dependencies called out by the individual example README. From the repository root or installed workspace:

make install
make env-init
make list
make init example-01
make run example-01 server

In a second terminal:

make run example-01 client

To remove the example's disposable runtime snapshot: make clean example-01. Certificates and shared secrets are preserved. The default external runtime root is /opt/agent-nebula/examples; override it with AGENT_NEBULA_EXAMPLES_ROOT as needed. See standalone setup and catalog.

Example catalogs

Standalone — examples/

Run without Agent Nebula Registry registration, Nginx, or ngrok. Local TLS/security prerequisites vary by example.

#	Example	Demonstrates
01	A2A Hello	Minimal A2A client/server smoke test. Resolves the Agent Card and invokes one hello skill through JSON-RPC over local HTTP.
02	A2A Multi-Skill	Establishes multi-skill as the normal SecureAgent model. Advertises three skills and makes the client explicitly select, invoke, and validate every skill.
03	A2A Multi-Binding	Registers the same skills once and verifies every skill independently over JSON-RPC, HTTP+JSON, and gRPC using binding-specific client instances.
04	A2A HTTPS	Retains the multi-skill model and adds certificate-verified HTTPS using a generated local CA and server identity; the client tests every skill without disabling TLS verification.
05	A2A Multi-Binding + TLS	Verifies every skill over JSON-RPC/HTTPS, HTTP+JSON/HTTPS, and gRPC/TLS.
10	API-Key Protected Agent	Verifies an A2A APIKeySecurityScheme using an externally configured header credential and native SDK invocation.
11	HTTP Authentication	Verifies HTTPAuthSecurityScheme with an opaque Bearer credential; HTTP Bearer syntax remains distinct from OAuth.
12	OpenID Connect	Verifies OpenIdConnectSecurityScheme with a locally provisioned test JWT and issuer/audience/signature validation.
13	Mutual TLS	Verifies MutualTlsSecurityScheme with mandatory client-certificate authentication at the TLS boundary.
14	Multiple Security Schemes	Verifies compound A2A security by requiring API key AND HTTP Bearer in one SecurityRequirement.
15	Native A2A Tasks	Verifies native a2a-sdk Message and Task execution, artifacts, get_task(), and list_tasks() with application-owned Task lifecycle.
17	Native A2A Artifacts	Verifies native artifact IDs, names, Parts, and TaskStore persistence through get_task().
18	Native A2A Streaming	Verifies streaming=true with native Task, status, and artifact update events through Client.send_message().
19	Native A2A Push Notifications	Verifies native push configuration create/get/list/delete operations and callback delivery.
20	Native A2A Extended Agent Card	Verifies authenticated native get_extended_agent_card() retrieval of a distinct richer Agent Card.
21	Combined Native A2A Capabilities	Combines native streaming, Task/artifact, push-notification, and Extended Agent Card capabilities in one scenario.
22	A2UI Basic	Verifies an application-owned A2UI v1.0 Basic Catalog presentation transported through native A2A.
23	A2UI Rich	Verifies an application-owned Agent Nebula Rich Catalog presentation over native A2A.
24	A2UI Catalog Negotiation	Verifies AgentCard A2UI catalog advertisement and per-turn renderer capability negotiation.
25	A2UI Multi-Skill Results	Verifies multiple native A2A skills independently producing application-owned A2UI results.
26	A2UI Actions	Verifies browser A2UI actions and synchronized state through the native A2A execution path.
27	A2UI Forms	Verifies browser-edited form state and submission through native A2A execution.
28	A2UI Tables	Verifies a Rich Catalog DataTable driven by application data.
29	A2UI Charts	Verifies a Rich Catalog BarChart driven by application data.
30	A2UI Multi-Skill	Verifies AgentCard-driven skill selection with different A2UI surfaces per skill.
31	A2UI + Native Tasks	Verifies a native A2A Task whose artifact carries an application-owned A2UI presentation.
32	A2UI + Native Streaming	Verifies native A2A streaming artifact updates producing visible incremental A2UI updates.

Agent Nebula integrated — examples-nebula/

These examples use Agent Nebula registration/discovery and, where applicable, hosted OAuth and skill scopes. For hosted Explorer to reach a developer-run agent, its advertised Agent Card and A2A endpoints must be publicly reachable. Configure the public endpoint using the Nginx + ngrok setup guide.

#	Example	Demonstrates
06	Agent Nebula Registration & Discovery	Registers the provider with Agent Nebula Registry, discovers it by capability, and invokes every skill through the discovered record.
07	Agent Nebula OAuth	Adds OAuth-protected A2A invocation after Registry discovery and verifies every skill.
08	Skill-Level OAuth	Verifies deterministic skill selection and distinct least-privilege OAuth scopes per skill.
09	Agent-to-Agent	Runs a dual-role SecureAgent that serves A2A while discovering and invoking a downstream Registry provider.
16	Native A2A Tasks + HTTPS + OAuth	Combines native Message/Task execution with Agent Nebula registration/discovery, HTTPS, and OAuth.
33	A2UI + HTTPS + OAuth	Verifies existing Agent Nebula HTTPS/OAuth security protecting native A2A carrying A2UI.
34	A2UI Combined	Combines HTTPS/OAuth, multi-skill dispatch, native Task/streaming, and A2UI without new protocol abstractions.

Agent Nebula Enterprise Registry Hub

Agent Nebula provides a hosted environment for publishing and discovering A2A agents and testing security-controlled invocation. The platform includes an A2A Registry, Playground, Explorer, OAuth services, policy services, and account management.

The account ownership model is Publisher → Provider → Agents: a publisher account manages providers; a provider publishes and manages agent registrations. An Agent Card describes the agent's capabilities, endpoints, and advertised security requirements. Registry discovery and Explorer invocation require reachability and appropriate authorization; successful registration alone does not prove the agent is reachable.

Start at agentnebula.ai to create an account. Then follow the existing Agent Nebula integration guide and registration/discovery example for provider onboarding, certificate enrollment, onboarding credentials, registration, discovery, and invocation. Platform-integrated examples provide the ordered test path. For hosted onboarding, see the registration guide, OAuth and policy guide, and Nginx + ngrok setup guide.

Developer documentation

• Standalone setup and complete catalog
• Agent Nebula setup and complete catalog
• Architecture and repository boundaries
• Configuration reference
• Security and authentication examples
• Initialization and external filesystem
• Adding an example
• Agent Nebula integration
• A2UI integration

Repository conventions

Examples are executable acceptance scenarios, not illustrative snippets: clients must exercise the capabilities advertised by their example and exit nonzero on assertion failure. Preserve numbered example IDs and the shared make init/run/clean example-NN lifecycle. Application code stays at the SecureAgent public boundary; do not reimplement A2A protocol handling, duplicate security enforcement, or commit credentials, certificates, or runtime output.

Agent Nebula hosted onboarding guides

• Account, provider, certificates, agent registration, and discovery
• OAuth-scoped skills and policy-controlled invocation
• Nginx + ngrok integration status

For publicly reachable registered agents, see Nginx + ngrok setup.