GitHub Actions AI Agent Monitoring

Step 1 — Add your Nexus API key as a GitHub secret

Go to your GitHub repository → Settings → Secrets and variables → Actions → New repository secret.

Create a secret named NEXUS_API_KEY and paste your Nexus API key. You can create one at /dashboard/keys.

Step 2 — Add the workflow YAML

Create .github/workflows/ai-agent.yml:

name: AI Agent CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  run-agent:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Run AI agent with Nexus tracing
        env:
          NEXUS_API_KEY: ${{ secrets.NEXUS_API_KEY }}
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: node scripts/run-agent.js

Step 3 — Wrap your agent in a Nexus trace

Create the script referenced by the workflow. The Nexus SDK wraps your agent in a trace and records each step as a span.

TypeScript

import Nexus from '@nexus-ai/sdk'

const nexus = new Nexus({ apiKey: process.env.NEXUS_API_KEY! })

async function runCiAgent() {
  const trace = await nexus.traces.create({
    agent_id: 'ci-agent',
    name: `CI run — ${process.env.GITHUB_RUN_NUMBER ?? 'local'}`,
    started_at: new Date().toISOString(),
  })

  try {
    const fetchSpan = await nexus.spans.create({
      trace_id: trace.id,
      name: 'fetch-context',
      started_at: new Date().toISOString(),
    })
    const context = await fetchBuildContext()
    await nexus.spans.update(fetchSpan.id, {
      ended_at: new Date().toISOString(),
      status: 'ok',
    })

    const llmSpan = await nexus.spans.create({
      trace_id: trace.id,
      name: 'llm-analysis',
      started_at: new Date().toISOString(),
    })
    const analysis = await callLLM(context)
    await nexus.spans.update(llmSpan.id, {
      ended_at: new Date().toISOString(),
      status: 'ok',
      output_tokens: analysis.usage.output_tokens,
    })

    await nexus.traces.update(trace.id, {
      ended_at: new Date().toISOString(),
      status: 'ok',
    })
    return analysis
  } catch (error) {
    await nexus.traces.update(trace.id, {
      ended_at: new Date().toISOString(),
      status: 'error',
      error: error instanceof Error ? error.message : String(error),
    })
    throw error
  }
}

runCiAgent().catch((e) => { console.error(e); process.exit(1) })

Python

import os
import nexus

client = nexus.Nexus(api_key=os.environ["NEXUS_API_KEY"])

def run_ci_agent():
    run_number = os.environ.get("GITHUB_RUN_NUMBER", "local")
    trace = client.traces.create(
        agent_id="ci-agent",
        name=f"CI run — {run_number}",
        started_at=nexus.now(),
    )
    try:
        with client.span(trace.id, "fetch-context"):
            context = fetch_build_context()

        with client.span(trace.id, "llm-analysis") as span:
            analysis = call_llm(context)
            span.output_tokens = analysis.usage.output_tokens

        client.traces.update(trace.id, status="ok", ended_at=nexus.now())
        return analysis
    except Exception as e:
        client.traces.update(
            trace.id, status="error", ended_at=nexus.now(), error=str(e)
        )
        raise

run_ci_agent()

What you'll see in the dashboard

Each GitHub Actions run creates one trace in Nexus, named with the run number (e.g., CI run — 42). The trace waterfall shows each span with its duration, token counts, and status.