wayfound

name	wayfound
description	Integrate AI agents with Wayfound's supervision and observability platform. Sends session transcripts for analysis, compliance monitoring, and performance evaluation. Use when the user wants to add Wayfound to their agent, send conversations to Wayfound, set up agent supervision, or monitor AI agent performance. Supports Python SDK, JavaScript SDK, and REST API.
metadata	{"author":"wayfound","version":"1.0"}

Wayfound Integration

Wayfound is an AI agent supervision platform. It analyzes agent-user conversations for performance, compliance, and knowledge gaps. Send session transcripts via SDK or REST API, and Wayfound returns analysis including guideline violations, improvement suggestions, and performance metrics.

Docs: https://docs.wayfound.ai API reference: https://wayfound-api.readme.io/reference

Prerequisites

Before integrating, the developer needs:

• A Wayfound account at https://app.wayfound.ai
• An agent created on the platform with a name, role, and goal. The goal should have clear, verifiable success criteria — Wayfound's supervisor evaluates sessions against it.
• An API key — created on the Settings > Connections page (requires admin permissions)
• The Agent ID — found on the agent's Connection page

Set these as environment variables (both SDKs read them automatically):

export WAYFOUND_API_KEY="your-api-key"
export WAYFOUND_AGENT_ID="your-agent-id"

Message Format

All integration methods use the same message schema. Define messages once, use them with any method.

Each message in the array:

{
  "timestamp": "2025-01-15T10:00:00Z",
  "event_type": "assistant_message",
  "attributes": {
    "content": "Hello! How can I help you today?"
  }
}

Field	Type	Required	Description
timestamp	string	Yes	ISO 8601 datetime of when the message occurred
event_type	string	Yes	One of the 14 supported event types listed below
attributes	object	No	Event-specific data. Use content for message text
label	string	No	Classification label for the event
description	string	No	Additional context about the event

The messages array has a 750 KB size limit.

Event Types

There are 14 supported event types. The AI Supervisor reasons about all of them when analyzing sessions.

Event Type	Purpose	Key Attributes
user_message	User's input	content
assistant_message	Agent's response	content, model_name, tokens_total, latency_ms
system_message	Background system actions	content
developer_message	Internal dev/debug logs	content
structured_message	Structured options presented to user	options (array of {title, value})
reasoning_step	Agent's internal reasoning	thought
tool_call	External tool/API invocation	tool_name, tool_input, tool_output, success, latency_ms
agent_call	Delegation to another agent	external_id, input
user_feedback	User rating or reaction	feedback_type (thumbs_up_down or stars), rating
button_click	User clicked a UI button	button_id
link_click	User clicked a link	url
agent_handoff	Transfer to human agent	reason
human_review	Supervisor/human follow-up	approver_id, status
custom_event	Any domain-specific event	event_name, details

Event examples

Tool call:

{
  "timestamp": "2025-01-15T10:00:03Z",
  "event_type": "tool_call",
  "label": "Tool Call: PMService.getProjectData",
  "description": "Fetched summary for Project Alpha",
  "attributes": {
    "tool_name": "PMService",
    "tool_input": { "projectId": "Alpha" },
    "tool_output": { "status": "On Track", "completion": 80 },
    "success": true,
    "latency_ms": 95
  }
}

Reasoning step:

{
  "timestamp": "2025-01-15T10:00:01Z",
  "event_type": "reasoning_step",
  "label": "Reasoning Step",
  "description": "Determine which service to call first",
  "attributes": {
    "thought": "Fetch high-level project data, then drill into trends."
  }
}

Agent call:

{
  "timestamp": "2025-01-15T10:00:09Z",
  "event_type": "agent_call",
  "label": "Agent Call: RiskAgent",
  "description": "Requested project risk evaluation",
  "attributes": {
    "external_id": "agent-42",
    "input": { "projectId": "Alpha" }
  }
}

User feedback:

{
  "timestamp": "2025-01-15T10:05:05Z",
  "event_type": "user_feedback",
  "label": "User Feedback",
  "description": "User rated the response",
  "attributes": {
    "feedback_type": "thumbs_up_down",
    "rating": "thumbs_up"
  }
}

Python SDK

Install:

pip install wayfound

Requires Python 3.8+.

Create a session

from wayfound import Session

session = Session(
    wayfound_api_key="your-api-key",
    agent_id="your-agent-id"
)

messages = [
    {
        "timestamp": "2025-01-15T10:00:00Z",
        "event_type": "assistant_message",
        "attributes": {"content": "Hello! How can I help?"}
    },
    {
        "timestamp": "2025-01-15T10:00:05Z",
        "event_type": "user_message",
        "attributes": {"content": "What's the status of Project Alpha?"}
    },
    {
        "timestamp": "2025-01-15T10:00:08Z",
        "event_type": "assistant_message",
        "attributes": {"content": "Project Alpha is on track for delivery next Friday."}
    }
]

result = session.create(messages=messages)

If WAYFOUND_API_KEY and WAYFOUND_AGENT_ID are set as environment variables, the constructor needs no arguments:

session = Session()

Synchronous mode

By default, create() returns immediately and analysis runs in the background. Set is_async=False to wait for analysis results:

result = session.create(messages=messages, is_async=False)

if "compliance" in result:
    violations = [item for item in result["compliance"] if not item["result"]["compliant"]]
    if violations:
        print(f"Found {len(violations)} guideline violations")

Append to a session

Add more messages to an existing session:

additional_messages = [
    {
        "timestamp": "2025-01-15T10:05:00Z",
        "event_type": "user_message",
        "attributes": {"content": "Can you also check Project Beta?"}
    }
]

session.append_to_session(additional_messages)

Visitor and account tracking

Track who is interacting with the agent:

session = Session(
    wayfound_api_key="your-api-key",
    agent_id="your-agent-id",
    visitor_id="user-123",
    visitor_display_name="Jane Smith",
    account_id="acct-456",
    account_display_name="Acme Corp",
    metadata={"source": "web", "environment": "production"}
)

JavaScript SDK

Install:

npm install wayfound

Create a session

import { Session } from "wayfound";

const session = new Session({
  wayfoundApiKey: "your-api-key",
  agentId: "your-agent-id"
});

const messages = [
  {
    timestamp: "2025-01-15T10:00:00Z",
    event_type: "assistant_message",
    attributes: { content: "Hello! How can I help?" }
  },
  {
    timestamp: "2025-01-15T10:00:05Z",
    event_type: "user_message",
    attributes: { content: "What's the status of Project Alpha?" }
  },
  {
    timestamp: "2025-01-15T10:00:08Z",
    event_type: "assistant_message",
    attributes: { content: "Project Alpha is on track for delivery next Friday." }
  }
];

const result = await session.create({ messages });

If WAYFOUND_API_KEY and WAYFOUND_AGENT_ID are set as environment variables, the constructor needs no arguments:

const session = new Session({});

Synchronous mode

Set async: false to wait for analysis results:

const result = await session.create({ messages, async: false });

Append to a session

Add more messages to an existing session:

const additionalMessages = [
  {
    timestamp: "2025-01-15T10:05:00Z",
    event_type: "user_message",
    attributes: { content: "Can you also check Project Beta?" }
  }
];

await session.appendToSession({ messages: additionalMessages });

Visitor, account, and metadata tracking

const session = new Session({
  wayfoundApiKey: "your-api-key",
  agentId: "your-agent-id",
  visitorId: "user-123",
  visitorDisplayName: "Jane Smith",
  accountId: "acct-456",
  accountDisplayName: "Acme Corp",
  metadata: { source: "web", environment: "production" }
});

REST API

For languages without an SDK, use the REST API directly.

Create a session

curl -X POST https://app.wayfound.ai/api/v2/sessions \
  -H "Authorization: Bearer $WAYFOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "your-agent-id",
    "messages": [
      {
        "timestamp": "2025-01-15T10:00:00Z",
        "event_type": "assistant_message",
        "attributes": {"content": "Hello! How can I help?"}
      },
      {
        "timestamp": "2025-01-15T10:00:05Z",
        "event_type": "user_message",
        "attributes": {"content": "What is the status of Project Alpha?"}
      }
    ]
  }'

Response:

{
  "id": "9f71c6ef-d423-4757-b39f-7118fe87adf6",
  "createdAt": "2025-01-15T10:01:00.000Z"
}

Append to a session

curl -X PUT https://app.wayfound.ai/api/v2/sessions/SESSION_ID \
  -H "Authorization: Bearer $WAYFOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "timestamp": "2025-01-15T10:05:00Z",
        "event_type": "user_message",
        "attributes": {"content": "Follow-up question here"}
      }
    ]
  }'

Optional parameters

Include these in the create request body as needed:

Parameter	Type	Description
async	boolean	Set to false to block until analysis completes (default: true)
visitorId	string	Unique identifier for the end user
visitorDisplayName	string	Display name for the end user
accountId	string	Unique identifier for the user's account/org
accountDisplayName	string	Display name for the account
applicationId	string	Groups sessions by application in multi-agent setups
metadata	object	Arbitrary key-value pairs attached to the session

Key Concepts

Async vs sync processing: By default, session creation returns immediately with a session ID while analysis runs in the background. Set async: false (REST/JavaScript) or is_async=False (Python) to wait for analysis results including compliance checks.

Appending messages: Use the session ID from the create response to append additional messages later. This is useful for long-running conversations where you want to send messages incrementally rather than waiting for the full conversation to complete.

Visitor and account tracking: Attach user identity (visitor_id, visitor_display_name) and organization identity (account_id, account_display_name) to sessions. These appear in Wayfound's Visitors tab for tracking interactions across sessions.

Session metadata: Attach arbitrary key-value pairs to sessions for filtering and analysis in the Wayfound dashboard (e.g., {"source": "web", "environment": "production", "model": "gpt-4"}).

Application ID: In multi-agent architectures, use application_id to group sessions by application. This links sessions to a specific application context in Wayfound.

Test mode: Use POST /api/v2/sessions/test/completed (same request body as the create endpoint) to submit test sessions during development. Test sessions are analyzed but flagged separately in the dashboard.

Message size limit: The messages array is limited to 750 KB per request. For very long conversations, send messages incrementally using the append endpoint.

Common Patterns

Sending a completed conversation

The simplest integration — collect all messages during the conversation, then send them to Wayfound after the session ends:

from wayfound import Session

def run_agent_session(user_input):
    messages = []
    # ... your agent conversation loop ...
    # Each turn, append to messages with timestamp, event_type, and attributes

    # After the conversation ends, send to Wayfound
    session = Session()
    session.create(messages=messages)

Streaming messages during a conversation

For long-running sessions, create the session with the first batch of messages, then append as the conversation continues:

from wayfound import Session

session = Session()

# After the first exchange
result = session.create(messages=initial_messages)
# session.session_id is now set from the response

# As the conversation continues
session.append_to_session(new_messages)

# After another exchange
session.append_to_session(more_messages)