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?"
  }
}

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 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:

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)