AG-UI

Quick Triage

• Use this skill when the task is protocol-level integration between agent backend and UI client.
• Switch to

  $langgraph

  when graph orchestration/checkpoint logic is the primary issue.
• Switch to

  $langchain

  when chain or tool orchestration internals are the primary issue.
• Switch to

  $copilotkit

  when CopilotKit hooks/provider behavior is primary.

Workflow

1. Define integration mode. Choose client-side

   HttpAgent

   , custom

   AbstractAgent

   , or middleware bridge.
2. Lock event subset and ordering. Map required lifecycle, text, tool, and state events before implementation.
3. Implement lifecycle first. Guarantee

   RUN_STARTED

   and

   RUN_FINISHED/RUN_ERROR

   framing around all runs.
4. Implement message and tool streams. Ensure tool call start/args/end/result sequence is valid and complete.
5. Implement state synchronization. Choose snapshot-only, delta-only, or hybrid strategy intentionally.
6. Add middleware with explicit order. Enforce auth, filtering, and logging without mutating protocol invariants.
7. Validate against event traces. Use deterministic replay to confirm ordering and payload shape.

Default Patterns

• Emit minimal valid event streams rather than custom ad-hoc payloads.
• Keep tool result payloads parseable and bounded.
• Prefer explicit event schemas over inferred client parsing.
• Keep protocol payloads transport-agnostic.

Failure Modes

• Out-of-order lifecycle or tool events.
• Partial tool-call streams without terminal result events.
• State delta application mismatch on client.
• Middleware mutating payloads into non-compliant shapes.

Reference Map

• Event contracts:

  references/event-contracts.md

• State sync strategy:

  references/state-sync.md

• Middleware usage:

  references/middleware-patterns.md

• Integration checklist:

  references/integration-checklist.md