agent-signal

Implement event-driven agent background work using sources, signals, actions, and policies.

Updated Jan 27, 2026
One-click install
npx skills add https://github.com/SmallAi-API/smaihub --skill agent-signal-smallai-api
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: agent-signal
Source: https://github.com/SmallAi-API/smaihub/tree/main/.agents/skills/agent-signal
Command: npx skills add https://github.com/SmallAi-API/smaihub --skill agent-signal-smallai-api

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Building event-driven background work for agents often couples side effects to the foreground chat request, making flows hard to deduplicate, trace, and extend. This Skill provides a consistent runtime model (source event → signal interpretation → action execution) so background agent work stays decoupled, idempotent, and observable. ## Core Features & Use Cases - Source, Signal, and Action Handlers: Register typed handlers with defineSourceHandler, defineSignalHandler, and defineActionHandler, then bundle them into installable policies. - Sync and Async Execution Entry Points: Choose between immediate execution, controlled backend execution, or queued out-of-band processing via Upstash Workflow. - Self-Iteration Receipts: Enqueue execAgent runs for memory and skill writes, then project user-visible receipts from the agent.execution.completed completion path. - Observability and Debugging: Use shared OTEL tracers, metrics, trace projection, and a development workflow snapshot bridge to inspect chains. - Use Case: When a user message signals feedback about memory, emit an agent.user.message source, route it through satisfaction and domain signal handlers, and enqueue a memory action whose receipt appears after the background run completes. ## Quick Start Use the agent-signal skill to add a new source handler and policy for a background agent workflow, then wire observability and tests.

Frequently Asked Questions about agent-signal

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a new Agent Signal source handler?

Define or reuse a source type in the shared sourceTypes catalog, then register a handler with defineSourceHandler that interprets the payload and returns dispatch status with signals. Bundle it via defineAgentSignalHandlers and register the policy in the policies index.

What is the difference between a source, signal, and action?

A source is a normalized external fact like a user message, a signal is a reusable semantic interpretation derived from sources, and an action is a concrete side effect executed by the runtime. Keep interpretation in source and signal handlers and side effects in action handlers.

When should I use enqueueAgentSignalSourceEvent instead of emit?

Use enqueueAgentSignalSourceEvent when the caller should return quickly and let Upstash Workflow process the event out-of-band. Use emitAgentSignalSourceEvent when a server-owned producer should execute the pipeline immediately in the foreground.

Why are memory or skill receipts missing after an action applied?

Receipts are projected from the agent.execution.completed event, not from the enqueue action. Verify the action enqueued execAgent with an Agent Signal marker, the completion payload carried selfIteration finalState, and the completion policy was wired with onSelfIterationCompleted.

How do I prevent duplicate action execution on retries?

Use stable source dedupe keys, consistent scopeKey values across retries and workflow handoff, and idempotency checks inside action handlers. The runtime guard state and action idempotency policy handle repeated delivery of the same source.