Building Your First OSSA Agent: Step-by-Step Tutorial

This tutorial provides an engineering-first path to building a validated OSSA agent. We will build a Code Review Agent that implements four of the production pillars: deterministic completion signals, capability abstraction, observability, and resource constraints.

Time Required: 25 minutes Stack: Node.js (TS) or Python 3.9+

---

Step 1: Initialize the Environment

The OSSA CLI provides the validation engine. Install it globally:

npm install -g @bluefly/openstandardagents
ossa version # Should be v0.3.6

---

Step 2: Define the Declarative Manifest

Unlike traditional frameworks where the agent logic is buried in code, OSSA uses a Declarative Manifest. This separates the intent (governance) from the implementation (runtime).

Create code-reviewer.ossa.yaml:

apiVersion: ossa/v0.4.0
kind: Agent
metadata:
  name: security-audit-agent
  description: "Analyzes pull requests for CVEs and logic flaws"

spec:
  role: "Expert Security Engineer"
  
  # Pillar 4: Capability Abstraction (BAT Pattern)
  capabilities:
    - type: tool-use
      protocol: mcp
      tools:
        - name: read_git_diff
          description: "Fetch changes from the current branch"
        - name: query_cve_db
          description: "Search for known vulnerabilities in dependencies"

  # Pillar 3: Efficiency Tiers
  efficiency:
    tier: standard
    promptCaching: true

  # Pillar 1: Deterministic Completion Signals
  orchestration:
    completionSignals:
      - type: success
        outputs: ["audit_report", "vulnerability_count"]
      - type: error
        outputs: ["stack_trace", "retry_hint"]

  # Pillar 9: Infrastructure Substrate
  resources:
    limits:
      cpu: "1000m"
      memory: "2Gi"

---

Step 3: Validate the Contract

Run the validator. This ensures your agent is compatible with the OSSA v0.3.6 JSON Schema.

ossa validate code-reviewer.ossa.yaml
# ✓ Valid OSSA v0.3.6 manifest detected.

---

Step 4: Implementation (Two Paths)

Option A: TypeScript Implementation

OSSA provides auto-generated types to ensure your runtime matches your manifest.

ossa generate types code-reviewer.ossa.yaml --output src/types.ts

Implementation Snippet (agent.ts):

import { Agent, CompletionSignal } from '@bluefly/openstandardagents-sdk';
import { SecurityAuditAgent } from './types';

const agent = new Agent<SecurityAuditAgent>('./code-reviewer.ossa.yaml');

agent.on('tool_call', async (call) => {
  console.log(`Pillar 7: Executing discovery-linked tool: ${call.name}`);
});

const result = await agent.run({ pr_id: 1234 });

// Pillar 1: Accessing structured output
if (result.status === 'success') {
  console.log(`Audit complete. Found ${result.payload.vulnerability_count} issues.`);
}

Option B: Python Implementation (New in v0.3.6)

Leverage the new functional Python SDK for data science environments.

from ossa import Agent, EfficiencyTier

# Load and validate
agent = Agent.from_yaml("code-reviewer.ossa.yaml")

# Execute with explicit cost controls
response = agent.execute(
    input={"source_code": "..." },
    tier=EfficiencyTier.STANDARD
)

# Implementation follows the ReAct pattern (Yao et al., 2022)
print(f"Reasoning Trace: {response.trace}")

---

Step 5: Verification & Observability

To satisfy Pillar 5 (Metrics), production agents must export telemetry. OSSA natively supports OpenTelemetry semantic conventions.

# Start a local Phoenix observability collector
docker run -p 6006:6006 arize-phoenix

# Run agent with OTel enabled
export OSSA_OTEL_ENDPOINT=http://localhost:6006
npm run start:agent

---

Summary of Results

By following this tutorial, you have moved from a "prompt in a string" to a Production Agent Substrate:

1. Contract-First: Your agent's capabilities are validatable before execution.
2. Language Agnostic: The same manifest works in TS and Python.
3. Observability-Ready: Your reasoning traces are ready for Langfuse or Phoenix.

---

Educational Resources:

• ReAct Research Paper (arXiv:2210.03629): The logic behind OSSA's tool-calling loop.
• OSSA v0.3.6 Specification Reference: Detailed schema definitions.
• NIST AI RMF: How OSSA aligns with federal AI safety standards.