Overview

Zowie External Agents enable organizations to build custom AI agents or integrate existing ones using purpose-built SDKs, providing secure access to internal systems and expert services while maintaining complete observability through Supervisor—integrating seamlessly with Zowie's platform today via Decision Engine and tomorrow through Orchestrator Routing.

This powerful capability bridges the gap between your automation workflows and internal systems that cannot be exposed through public APIs, while giving you complete control over business logic, data, and infrastructure.

What are Zowie External Agents?

Zowie External Agents is a comprehensive solution for extending your AI capabilities beyond platform limitations. It provides:

Purpose-built SDKs in Python and TypeScript/Node.js for building sophisticated agents
Automatic Supervisor integration for complete observability without additional instrumentation
Flexible platform integration through Decision Engine (available now) and Orchestrator Routing (coming soon)
Enterprise-grade security with multiple authentication methods and compliance-ready audit trails

Unlike platform-locked solutions that force you into proprietary frameworks, Zowie External Agents provides development freedom with enterprise control.

Why Use External Agents?

External Agents are essential when your organization needs to:

Leverage Existing Investments

Connect agents you've already built, preserving your development efforts and domain expertise. The SDK wraps existing agents without requiring rewrites.

Build with Flexibility

Create new agents using familiar programming languages (Python or TypeScript/Node.js) and frameworks, not proprietary platforms. Implement business logic that requires code-level control.

Maintain Security Boundaries

Keep sensitive systems behind firewalls while enabling AI capabilities. Process data within your infrastructure to meet compliance requirements.

Unified Observability

Monitor all agents—internal and external—through Supervisor, providing a single pane of glass for operations. Every LLM call, API request, and routing decision is automatically tracked.

Platform Agnostic

Integrate with Decision Engine today and Orchestrator Routing tomorrow, future-proofing your agent architecture without code changes.

Core Capabilities

Zowie External Agents is built on three foundational pillars:

1. Development Freedom - External Agent SDK

The External Agent SDK provides purpose-built frameworks that empower developers to build sophisticated agents with complete control over business logic.

Multi-language Support

Python SDK for data-intensive operations and ML integrations
TypeScript/Node.js SDK for high-performance services
Type-safe development with Pydantic (Python) and Zod (TypeScript)

Built-in LLM Integration

Pre-configured clients for Google Gemini and OpenAI GPT models
Automatic prompt construction with persona and context injection
Structured output generation for type-safe data extraction

HTTP Client with Auto-tracking

Connect to any internal API with automatic event logging
Configurable timeout and retry logic
Header and body filtering for sensitive data

Context Management

Handle conversation history, metadata, and routing decisions seamlessly
Maintain state across multiple agent interactions
Preserve context between internal and external agents

2. Unified Observability - Supervisor Integration

Every external agent action is automatically tracked and visible in Supervisor, providing enterprise-grade monitoring without additional instrumentation.

Automatic Event Tracking

LLM Calls: Model used, prompts, responses, and execution time
API Calls: URLs, methods, headers (sanitized), request/response bodies, and latency
Routing Decisions: Transfer logic, target blocks, and decision criteria
Errors and Exceptions: Stack traces, error messages, and recovery actions

Performance Metrics

Response time distributions
Throughput and request volumes
Error rates and types
Resource utilization patterns

Compliance and Auditing

Complete audit trails with timestamps and metadata
User data handling tracked for privacy compliance
System access patterns recorded for security audits
Immutable logs for regulatory reporting

Zero Configuration Required

No additional code needed
Automatic event batching and transmission
Resilient to network issues
Minimal performance overhead

3. Flexible Integration - Platform Connectivity

External Agents integrate seamlessly with Zowie's platform, with support for multiple entry points.

Decision Engine Integration (Available Now)

Delegate workflow control to external agents
Conditional routing based on conversation context
State management across multiple agents
Automatic fallback handling on agent failure

Orchestrator Routing (Coming Soon)

Direct routing to external agents without Decision Engine
Dynamic agent selection based on capabilities
Load balancing across multiple instances
Priority handling for specialized routing

Enterprise Security

Multiple authentication methods: Bearer Token, API Key, Basic Auth
TLS encryption for all communications
IP whitelisting and rate limiting support
Configurable timeout and failure handling

External Agent SDK

The External Agent SDK is the cornerstone of Zowie's external agent strategy, providing developers with powerful, production-ready frameworks.

Available SDKs

Python SDK

Perfect for data-intensive operations, machine learning integrations, and teams with Python expertise.

Key Features:

Built on FastAPI for high-performance async operations
Full Pydantic v2 support for request/response validation
Thread pool execution with configurable workers
Compatible with pip, Poetry, and uv package managers

Links:

TypeScript/Node.js SDK

Ideal for high-performance services and teams working in JavaScript ecosystems.

Key Features:

Express-based with TypeScript-first design
Zod schemas for runtime validation
Native async/await patterns throughout
Compatible with npm, pnpm, and yarn package managers

Links:

Core SDK Features

Intelligent Context Management

Automatic conversation history handling
Metadata preservation across interactions
Seamless state management between agents

LLM Provider Integration

Pre-configured clients for Google Gemini and OpenAI GPT
Automatic prompt construction with persona and context injection
Structured output generation for type-safe responses

HTTP Client with Observability

Automatic request/response logging to Supervisor
Configurable timeout and retry logic
Header and body filtering for sensitive data protection

Development Experience

Comprehensive documentation and examples
Built-in testing utilities and mocks
Hot-reload support for rapid development
Production-ready deployment configurations

Quick Start Examples

Python Example

from zowie_agent_sdk import Agent, Context, ContinueConversationResponse

class CustomAgent(Agent):
    def handle(self, context: Context):
        # Access conversation history
        messages = context.messages

        # Use built-in LLM client
        response = context.llm.generate_content(
            messages=messages,
            system_instruction="You are a helpful customer service agent."
        )

        # Return conversational response
        return ContinueConversationResponse(message=response)

TypeScript Example

import { Agent, Context, AgentResponse } from "@zowieteam/zowie-agent-sdk";

class CustomAgent extends Agent {
    async handle(context: Context): Promise<AgentResponse> {
        // Access conversation history
        const messages = context.messages;

        // Use built-in LLM client
        const response = await context.llm.generateContent(
            messages,
            "You are a helpful customer service agent."
        );

        // Return conversational response
        return { type: "continue", message: response };
    }
}

Integration with Decision Engine

The External Agent block enables your Decision Engine workflows to delegate control to external agents. This powerful feature bridges the gap between your automation flows and internal systems that cannot be exposed through public APIs, while maintaining full control over the conversation flow.

Note: This feature is currently behind a feature flag and may not be available to all users.

Core Purpose

The External Agent block solves a critical challenge in process automation: securely accessing internal expert systems and private data sources that cannot have public API exposure.

When your workflow reaches an External Agent block, it:

Pauses execution and delegates control to your external agent
Waits for the agent to process the request
Routes the conversation based on the agent's response

This enables sophisticated integrations while keeping sensitive systems protected behind your firewall.

Configuration

Configure your External Agent block by setting up each section in the order they appear:

Endpoint

URL: Enter the full URL where your external agent is hosted

Example: https://agents.yourcompany.com/document-verification
Must be accessible from your Decision Engine instance
Use HTTPS for production environments

Authentication Methods

Select and configure one of three authentication methods to secure the connection:

1. Bearer Token

Enter the token value that will be sent in the Authorization header
Example token: abc123xyz
Your agent will receive: Authorization: Bearer abc123xyz

2. Custom Header

Specify the header name (e.g., X-API-Key)
Enter the header value (e.g., your-secret-key)
Useful for proprietary authentication schemes

3. Basic Auth

Enter the username
Enter the password
Credentials are base64 encoded automatically

Choose the authentication method that best aligns with your external agent's security requirements and existing infrastructure.

Routing

The External Agent block supports multiple routing paths based on response keys:

Dynamic Routing: Uses reference keys returned by the external agent to determine the next workflow block. You can define multiple reference key/target block pairs, allowing for flexible branching based on the agent's response
Failure Path: Activated when the agent encounters an error or cannot process the request

The routing decision is made based on the key value returned by the external agent, allowing for sophisticated branching logic within your processes.

Next Blocks

Configure the dynamic routing based on reference keys returned by your agent:

Reference Key: The key your agent returns to trigger this route

Example: completed, needs_review, documents_missing

Target Block: The process block to route to when this key is received

Select from your available workflow blocks

Click "Add next block" to configure multiple routing paths. Each reference key should map to a specific scenario your agent handles.

Additional Settings

Provide context to external agent (Optional)

Toggle this on to send additional context to your agent
Enter context information in the text field that appears
This context is sent with every request to help your agent make decisions
Example: Business rules, specific instructions

Failure Condition

Target Block: Select the block to route to when the agent fails

Handles timeouts, errors, or when the agent is unreachable
Always configure this to ensure your workflow can recover gracefully
Example: Route to Error Handler or Manual Review block

This failure path is triggered when:

The agent doesn't respond within the timeout period
The agent returns an error status
Network connectivity issues occur
The agent response cannot be parsed

Supervisor Integration

One of the most powerful aspects of Zowie External Agents is the automatic integration with Supervisor, providing complete observability for all external agent activities.

Unified Monitoring

External agents appear alongside internal Zowie agents in Supervisor, creating a single pane of glass for all AI operations.

What Gets Tracked Automatically:

Every LLM call with model, prompts, responses, and execution time
Every API call with URLs, methods, sanitized headers, bodies, and latency
All routing decisions with transfer logic and target blocks
Errors and exceptions with stack traces and recovery actions

Performance Visibility:

Real-time response time distributions
Throughput and request volume metrics
Error rates categorized by type
Resource utilization patterns

Conversation Flow Visualization:

Complete conversation timeline
Agent handoff points between internal and external agents
Decision branches and routing logic
User interaction patterns

Event Monitoring

When an external agent takes control:

The event automatically appears as "deferred" in the Supervisor
You can monitor processing time and identify bottlenecks
Full audit trail is maintained for compliance
Real-time log streaming during development

Operational Benefits

Debugging and Troubleshooting:

Real-time log streaming during development
Historical analysis for incident investigation
Correlation between multiple agent interactions
Performance bottleneck identification

Cost Optimization:

Track LLM token usage across all agents
Identify expensive operations and optimize
Analyze prompt strategies based on actual usage
Budget tracking and forecasting

Key Use Cases

Internal System Integration

Connect to proprietary databases, legacy systems, or sensitive internal services that must remain private. Your external agent acts as a secure bridge, processing requests and returning appropriate responses without exposing underlying systems.

Examples:

Query customer data from internal CRM systems
Access inventory management databases
Integrate with legacy mainframe systems
Connect to internal knowledge bases

Expert System Delegation

Leverage complex business logic or specialized knowledge bases that require developer expertise to maintain. External agents can make decisions based on intricate rules that would be difficult to implement directly in workflows.

Examples:

Apply multi-step verification rules
Implement dynamic pricing calculations
Process complex eligibility requirements
Execute specialized business workflows

Compliance & Security Requirements

Handle scenarios where regulatory or security constraints prevent direct API exposure. External agents can process sensitive data and return sanitized results appropriate for the conversation context.

Examples:

Process PII data within infrastructure boundaries
Apply industry-specific compliance rules (HIPAA, PCI-DSS)
Maintain data sovereignty requirements
Implement custom security protocols

Connect Existing Agents

Integrate agents you've already built in any language or framework. Preserve your development efforts and domain expertise while gaining Zowie platform capabilities.

Examples:

Wrap existing Python ML models
Integrate custom NLU services
Connect proprietary AI systems
Leverage existing automation investments

Real-World Example: Document Verification System

Consider a financial services company that needs to verify customer documents for account approval. Their verification system:

Contains sensitive customer data that cannot be exposed publicly
Uses complex business rules that vary by account type and jurisdiction
Requires integration with multiple internal databases
Must maintain complete audit trails for compliance

How It Works

1. Customer Request Customer asks: "What documents do I need to provide?"

2. Workflow Delegation Decision Engine routes to External Agent block, which sends the request to the document verification agent running in the company's secure infrastructure.

3. External Agent Processing The agent:

Queries internal customer database for account type
Checks regional compliance requirements from private compliance system
Evaluates previously submitted documents from document management system
Applies complex business rules based on risk profile and jurisdiction

4. Intelligent Response The agent returns:

Reference key for routing (e.g., documents_required, verification_complete, manual_review_needed)
Conversational response explaining what documents are needed and why
Metadata about the verification status for internal tracking

5. Workflow Continuation Decision Engine routes to the appropriate next block based on the reference key, continuing the automation flow while maintaining context.

Benefits Realized

Security maintained: Sensitive customer data never leaves internal systems
Flexibility preserved: Complex business rules updated by developers as needed
Full observability: Every database query and decision logged in Supervisor
Compliance met: Complete audit trail for regulatory requirements
Seamless experience: Customer receives intelligent, context-aware responses

How External Agents Respond

External agents built with the SDK can return two types of responses:

Continuation response: Sends a message to the user and continues the conversation within the current workflow context
Transfer response: Routes the conversation to a different block based on a reference key

The reference key returned by your agent must match one of the keys configured in your External Agent block's routing configuration (e.g., completed, needs_review, documents_missing).

For complete SDK documentation, code examples, and implementation guides for both response types, refer to the official SDK repositories on GitHub.

Questions & Answers

Q: How does the External Agent SDK differ from building agents from scratch?

A: The SDK provides production-ready frameworks with built-in LLM integration, automatic Supervisor observability, conversation management, and enterprise authentication. Building from scratch would require implementing all these capabilities yourself, taking months of development.

Q: Can I integrate agents I've already built?

A: Yes! The SDK is designed to wrap existing agents, adding Zowie platform integration and Supervisor visibility without requiring rewrites. Your existing business logic remains unchanged while gaining enterprise capabilities.

Q: What happens if an external agent fails or becomes unavailable?

A: The platform includes configurable timeout and failure handling. Failed requests automatically route to configured fallback blocks, ensuring conversation continuity. All failures are logged in Supervisor for troubleshooting.

Q: How do external agents access internal systems securely?

A: External agents run within your infrastructure, behind your firewall. They can access internal systems directly without exposing APIs externally. The SDK handles secure communication with Zowie's platform using your choice of authentication methods.

Q: Can external agents work with both Decision Engine and Orchestrator Routing?

A: Yes, agents built with the SDK are platform-agnostic. They work with Decision Engine today and will seamlessly integrate with Orchestrator Routing when available, protecting your development investment.

Q: What kind of agents are best suited for external development?

A: External agents are ideal for: specialized business logic, integration with internal systems, processing sensitive data, leveraging existing code bases, or any scenario requiring development flexibility beyond platform capabilities.