Asante Secure Multi-Agent Application

A production-style learning application for secure AI-agent operations at Asante Stays.

The project is deliberately split into layers:

• Operator API: FastAPI.

• Human authentication: OAuth-style Bearer JWT access tokens.

• Agent runtime: OpenAI Agents SDK.

• Agent tool protocol: MCP over Streamable HTTP.

• Workload identity: trusted SPIFFE IDs for Supervisor and Guest Support.

• Authorization boundary: Ruhusa 0.8.0 for delegated authority, policy, trusted invocation provenance, tool identity, revocation semantics, and execution fencing.

• Observability: OpenTelemetry traces and security/execution metrics, plus an OpenAI Agents tracing bridge.

• Reliability: bounded known-safe retries, server-derived idempotency, and fail-closed unknown outcomes.

• Release gate: deterministic authorization, attack, reliability, and agent-contract evals in GitHub Actions.

Phase 6 vertical slice: reliability + eval-gated CI

Phase 6 turns the security/reliability properties from documentation into a release gate. CI does not need an OpenAI API key: it evaluates deterministic invariants that must never depend on model behavior.

PR / push
  -> locked dependency sync
  -> ruff format/lint
  -> pytest
  -> deterministic release evals
       -> normal authorization cases
       -> delegation attack cases
       -> MCP authority-boundary checks
       -> idempotency/retry checks
       -> agent safety instruction contracts
  -> PASS only when every gate is green

The release thresholds are intentionally strict:

• deterministic pass rate: 100%;

• critical eval failures: 0;

• unauthorized side effects: 0.

Run the same gate locally:

uv run python -m asante_secure_multi_agent.evals --output eval-report.json

The command exits non-zero when the release gate fails, so the same behavior can block a pull request in GitHub Actions.

Reliability policy

The protected credit path now distinguishes retry safety:

• TransientCreditProviderError: the adapter knows no side effect happened, so a small bounded retry budget may be used;

• UnknownOutcomeCreditProviderError: execution may have happened, so the application does not blindly retry and Ruhusa is marked unknown;

• repeated identical logical credits in the same trusted task use a server-derived idempotency key and are deduplicated.

The model never supplies the idempotency key. It is derived from trusted task ID, reservation, action, and amount.

Deterministic attack/eval catalog

The Phase 6 gate includes cases for:

1. small allowed credit;

2. approval-required action produces no side effect;

3. policy-denied action produces no side effect;

4. delegated-limit bypass attempt;

5. widened child-grant attack;

6. cross-task grant replay;

7. MCP schema authority injection;

8. duplicate logical execution/idempotency;

9. known-safe transient retry;

10. unknown-outcome no-retry behavior; and

11. Supervisor/Guest Support safety-instruction contracts.

A future live-model eval suite can measure model behavior separately. The CI release gate remains deterministic so a security invariant never becomes a probabilistic test.

Related MCP server: titmas-agent-action-gate

Phase 5 vertical slice: end-to-end agent observability

Phase 5 adds OpenTelemetry without changing who is trusted or what Ruhusa allows.

HTTP /agent/run
  -> Bearer token verification
  -> human -> Supervisor -> Guest Support delegation
  -> OpenAI Agents workflow / handoff / generation structure
  -> Streamable HTTP MCP
  -> trusted task lookup
  -> Ruhusa admission
  -> Ruhusa execution-time revalidation
  -> protected credit side effect

The API returns a trace_id on POST /agent/run, POST /demo/credits, and GET /auth/whoami so an application result can be correlated with its trace.

What is traced

Phase 5 records structural and security metadata such as:

• authenticated vs rejected identity attempts;

• delegation depth and bounded credit limits;

• Supervisor / Guest Support agent runtime structure;

• MCP tool name and outcome;

• Ruhusa admission and revalidation effects;

• policy ID when one matched;

• protected side-effect outcome; and

• FastAPI request latency/status.

The application intentionally does not copy prompts, completions, tool arguments/results, reservation IDs, Bearer tokens, or human subject IDs into custom OpenTelemetry span attributes. OpenAI Agents native tracing remains enabled separately unless you disable it using the Agents SDK configuration.

OpenAI Agents -> OpenTelemetry bridge

The Agents SDK already traces agent runs, model generations, handoffs and tool calls. Phase 5 registers an additional tracing processor that mirrors the SDK's structure into the current OpenTelemetry trace. This preserves the native OpenAI trace destination while giving the application a vendor-neutral SRE trace that also contains HTTP, MCP, Ruhusa and execution spans.

MCP trace propagation

The MCP client injects W3C trace context into the Streamable HTTP headers. It also injects current trace context into hidden MCP _meta alongside the trusted task reference. That metadata is not part of the model-visible tool schema. The MCP server extracts it before creating the asante.mcp.issue_guest_credit span.

Metrics

Phase 5 emits low-cardinality metrics:

asante.authorization.decisions
asante.authorization.duration
asante.mcp.tool.calls
asante.credit.executions

Authorization metrics distinguish admission from execution-time revalidation. They do not carry operator, reservation or prompt data.

Exporters

Local development defaults to console output:

export ASANTE_OTEL_EXPORTER=console

To keep instrumentation active without exporting:

export ASANTE_OTEL_EXPORTER=none

To send OTLP/HTTP to an OpenTelemetry Collector or compatible backend:

export ASANTE_OTEL_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318

The OpenTelemetry SDK/exporters use the standard OTEL_EXPORTER_OTLP_* environment variables for further OTLP configuration.

Security chain preserved from Phases 1-4

Authentication
  Who is this human/workload?

Delegation
  What authority was passed to this workload?

MCP
  How does the agent reach the capability?

Authorization
  May this workload perform this exact action now?

Observability
  What happened, where did time go, and which security boundary stopped it?

Ruhusa remains the authorization boundary. OpenTelemetry observes decisions; it does not influence them.

Run locally

Requires Python 3.12+ and uv.

uv sync
export OPENAI_API_KEY="..."
export ASANTE_AUTH_MODE=dev
export ASANTE_DEV_JWT_SECRET="asante-local-development-only-change-me"
export ASANTE_OTEL_EXPORTER=console
uv run pytest
uv run uvicorn asante_secure_multi_agent.main:app --reload

Create a development access token:

TOKEN=$(uv run python -m asante_secure_multi_agent.identity.dev_token claire)

Open Swagger at http://127.0.0.1:8000/docs, click Authorize, paste the token, and call POST /agent/run. A successful response now includes both the Ruhusa task ID and an OpenTelemetry trace ID.

The normal learning cases remain:

• $20 credit -> allowed and executed;

• $40 credit -> blocked by the $25 Guest Support delegation;

• /demo/credits -> direct authenticated Ruhusa diagnostic path.

Phase 5 tests

Phase 5 preserves all identity, delegation, MCP and execution regressions and adds tests for:

1. W3C traceparent injection and trace-ID correlation;

2. OpenAI Agents span mirroring into OpenTelemetry;

3. parent/child trace structure between the application and agent runtime; and

4. preventing prompt/tool content from entering custom OTel attributes.

Roadmap

1. Prove secure tool execution with Ruhusa.

2. Add real supervisor -> specialist delegation grants.

3. Move the guest-credit tool surface to MCP.

4. Add authenticated human identity and trusted workload identity.

5. Add OpenTelemetry traces and security metrics.

6. Add agent evals and authorization attack tests to CI.

7. Add durable human approval workflow.

8. Replace in-memory stores with production backends/shared task state.

9. Split MCP/agent workloads and replace static SPIFFE assignment with SPIRE/SVID verification.