Skip to main content

​
Observe API

Use Observe.observe() to create spans for custom agent orchestration: planning, tool execution, policy checks, handoffs, retrieval, and other work that provider SDKs do not expose.

​
Wrap A Function

Wrap a tool call
import {
  ATTR_BEACON_EVENT_ACTION,
  ATTR_BEACON_EVENT_CATEGORY,
  ATTR_BEACON_HARNESS_NAME,
  ATTR_BEACON_TOOL_NAME,
  Observe,
} from "@asymptote/sdk";

const runSearch = Observe.observe(
  {
    name: "agent.tool.search",
    attributes: {
      [ATTR_BEACON_HARNESS_NAME]: "custom_agent",
      [ATTR_BEACON_EVENT_ACTION]: "tool.invoked",
      [ATTR_BEACON_EVENT_CATEGORY]: "tool",
      [ATTR_BEACON_TOOL_NAME]: "search_docs",
    },
  },
  async (query: string) => {
    return searchDocs(query);
  },
);

await runSearch("How does Beacon normalize endpoint events?");
await Observe.flush();
The wrapped function preserves the original return behavior for sync functions, promises, and async iterables. Errors are recorded on the span and then rethrown.

​
Observe Options

OptionPurpose
nameSpan name
spanKindOptional OpenTelemetry span kind
attributesSpan attributes, including Beacon compatibility attributes
ignoreInputDo not record asymptote.observe.input.count
ignoreOutputDo not record asymptote.observe.output.type

​
Avoid Sensitive Metadata

Set ignoreInput or ignoreOutput when wrapper metadata should avoid recording argument counts or output type.
Ignore input and output metadata
const lookupSecretSafely = Observe.observe(
  {
    name: "agent.secret.lookup",
    ignoreInput: true,
    ignoreOutput: true,
  },
  async (id: string) => lookupSecret(id),
);
Beacon compatibility attributes should still be chosen carefully. Do not place raw secrets, credentials, or high-risk prompt content in custom attributes.

​
Common Beacon Actions

Use Beacon compatibility attributes when a custom step should normalize into a known event category.
ActionTypical categoryExample use
prompt.submittedpromptUser prompt or agent turn
tool.invokedtoolFunction call, retrieval step, or external API call
command.executedcommandShell command or build step
file.modifiedfileAgent-created or edited file
mcp.tool_invokedmcpMCP server tool call
approval.requestedapprovalHuman review or policy gate
Wrap an MCP tool call
import {
  ATTR_BEACON_EVENT_ACTION,
  ATTR_BEACON_EVENT_CATEGORY,
  ATTR_BEACON_MCP_SERVER,
  ATTR_BEACON_MCP_TOOL,
  Observe,
} from "@asymptote/sdk";

const callMcpTool = Observe.observe(
  {
    name: "agent.mcp.call",
    attributes: {
      [ATTR_BEACON_EVENT_ACTION]: "mcp.tool_invoked",
      [ATTR_BEACON_EVENT_CATEGORY]: "mcp",
      [ATTR_BEACON_MCP_SERVER]: "docs",
      [ATTR_BEACON_MCP_TOOL]: "search",
    },
  },
  async (query: string) => searchDocsMcp(query),
);
See the SDK reference for the full attribute list.