Wayfound-AI/wayfound

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)