agent-nebula-secureagent-examples

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.

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.

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.

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.