Skip to main content

TAP Tagging Suggestions

TAP Integration Overview​

The TAP (The Ambassador Platform) integration provides suggestions-only tag and caption generation for TAP-owned post data. TAP sends post context and media to the AI service; the AI service returns suggested tags, optional captions, confidence, and reasoning without reading from or writing to TAP APIs.

What Is Currently Implemented​

1. Tagging Suggestions​

Purpose: Generate suggested tags and optional captions from caller-provided TAP post context and media.

What It Does:

  • Accepts batches of TAP posts through custom workflow routes
  • Uses tap-caption-tagging-agent to produce captions, tags, confidence, and reasoning
  • Normalizes suggested tag names before returning them
  • Supports synchronous requests and tracked create/start/poll runs
  • Does not call TAP APIs or mutate TAP posts

Current Capabilities:

  • Suggestions-only operation with no TAP dashboard credentials required
  • In-memory run tracking by default, with SQL persistence when configured
  • Per-post success/error results

Output: A response containing jobId, processed count, per-post captions/tags, confidence, reasoning, and errors.

Current Status: Active TAP tagging integration.

2. TAP Query Workflow​

Purpose: Answer bounded TAP questions from retrieved post and FAQ context.

What It Does:

  • Runs tap-query-workflow
  • Retrieves TAP context with TapQueryService
  • Synthesizes structured answers with tap-query-agent
  • Exposes a bounded synchronous compatibility route

Current Status: Active custom route. The retired async query routes return 410.

3. Topic Detection​

Purpose: Classify completed or quiet TAP student conversations into a stable topic taxonomy for downstream analysis.

What It Does:

  • Accepts ordered chat messages with external conversation/thread IDs when available
  • Falls back to generated internal conversation IDs when needed
  • Persists durable message metadata and short-lived message text
  • Uses local gates and candidate ranking before calling the TAP topic detection agent
  • Supports fast and full analysis modes with the same audit/output schema
  • Tracks provider request ID, latency, token usage, workflow step timings, candidate topics, final topics, evidence, and raw agent response

Current Status: Internal workflow/service path for RUU-37. It can be called on demand through POST /tap/workflows/topic-detection; scheduled polling is not wired yet.

Architecture Components​

Agents​

TAP currently keeps a small active product agent set:

  • TAP Caption and Tagging Agent - Suggestions-only captioning and tag generation from supplied post context and media.
  • TAP Query Agent - Synthesizes TAP query answers from retrieved post and FAQ context.
  • TAP Topic Detection Agent - Classifies completed chat conversations into topic keys with auditable evidence.

For detailed information including registry IDs, profile IDs, default prompts, and available tools, see TAP Agents.

Workflows​

TAP workflows and custom routes orchestrate bounded request processing:

  • Tagging Suggestions Route - Suggests captions and tags without TAP writes
  • TAP Query Route - Runs TAP query workflow synchronously
  • TAP Chat Workflow - Internal chat workflow entry point

For complete workflow documentation including step-by-step flows and implementation details, see TAP Workflows.

Tools​

The legacy TAP API tool registry still contains 13 tool wrappers under packages/domain-tap/src/tools/tap/, but those tools are not exposed through runtime tool routes for current TAP product traffic.

  • Post Operations - Query, fetch, and update posts with pagination and filtering
  • Tag Operations - Create, update, lookup, and attach global tags to posts
  • User Operations - Fetch user metadata and ambassador information
  • Dry-run support - Legacy mutation wrappers include dry-run handling for external API operations

For route status and legacy tool details, see TAP Tools and TAP Tools Detailed.

Operational Logging​

TAP uses Azure SQL for operational logging:

  • Active tagging suggestion jobs - TAP.log_TaggingSuggestionJobs
  • Active post suggestion results - TAP.log_TaggingSuggestionPostResults
  • Topic detection message ledger and results - TAP.data_ConversationMessages, TAP.data_ConversationMessageText, TAP.log_TopicDetectionConversationResults, and TAP.data_ConversationTopicAssignments
  • Legacy batch/caption/content-safety tables - retained for historical runs and compatibility

How It Works​

The active TAP tagging path follows a suggestions-only pipeline: receive post payloads → build per-post prompts → generate captions and tags → normalize tag names → return per-post results. It does not fetch TAP posts, create tags, attach tags, or update captions through TAP APIs.

For detailed workflow diagrams and step-by-step implementation, see TAP Workflows.

Key Features​

  • Suggestions-only tagging - TAP sends post context and media; the AI service returns suggested tags/captions without TAP API reads or writes
  • Tracked run support - Synchronous and create/start/poll execution patterns are available for tagging suggestions
  • Managed Identity Support - Secure authentication for Azure services without embedded keys

For detailed feature documentation and configuration options, see TAP Workflows.

Development & Testing​

  • Code Locations: TAP agents, workflows, routes, services, and legacy tools in packages/domain-tap/src/
  • Tests: Unit tests under packages/domain-tap/tests/ and shared route/service tests under tests/
  • MCP: TAP documentation remains searchable through the docs MCP server
  • Environment: Does not require TAP dashboard/public API credentials for tagging suggestions

For complete development setup, environment variables, and usage examples, see TAP Workflows.

Next Steps​

TAP Agents

Explore TAP captioning and moderation agents

TAP Workflows

Learn about tagging suggestion workflows

TAP Tools

Review TAP route status and legacy API tools