Agent Use Cases

See These Use Cases on the Web

Wiro publishes interactive, fullscreen showcases for the most common agent use cases. Each one walks through a real product story end-to-end — build, deploy, daily operation, brand-voice authoring, scheduled autopilot, and a self-healing climax under an upstream API break — so you can see what the patterns below look like before writing any code.

You can also browse every available pre-built agent at wiro.ai/agents/browse (the visual mirror of POST /Agent/List). Each agent template has its own marketing page at wiro.ai/agents/{slug} — for example wiro.ai/agents/social-manager, wiro.ai/agents/voice-receptionist, or wiro.ai/agents/blog-content-editor — with screenshots, default skills, credential requirements, and live tier pricing. The full URL for each agent in the Available Agents table below is https://wiro.ai/agents/{slug}.

Two Deployment Patterns

Every product built on Wiro agents follows one of two patterns. Choosing the right one depends on whether your users need to connect their own third-party accounts.

Pattern 1: Instance Per Customer

Most agents interact with external services — posting to social media, managing ad campaigns, sending emails. These require OAuth tokens or API keys that belong to the end user. Deploy a separate agent instance for each of your customers.

Why: Each customer connects their own accounts. Credentials are bound to the instance, isolated from other customers.

How: Call POST /UserAgent/Deploy once per customer, then use the OAuth flow to connect their accounts.

Real-World Examples

Pattern 2: Session Per User

For conversational agents that don't need per-user credentials. One agent instance serves many users, each identified by a unique sessionkey that isolates their conversation history.

Why: No third-party accounts to connect. The agent answers questions using its built-in knowledge or pre-configured data sources.

How: Deploy one instance via POST /UserAgent/Deploy, then send messages with different sessionkey values per user.

About sessionkey: This field is optional — if omitted, messages go into a shared "default" session. Reuse the same sessionkey to continue a conversation (the agent retrieves prior messages as context). Use a fresh UUID to start a new conversation. The common convention is one sessionkey per end-user (e.g. "user-456"), but you can also use it per-thread (e.g. "ticket-2025-0817") for products that group conversations by topic. See the Agent Messaging guide for how sessions work.

Real-World Examples

When to Use Which

Hybrid Pattern

A single product can combine both — a per-customer action agent plus a shared conversational agent sit side by side in the same frontend. For example:

• One Social Manager instance per customer (Pattern 1) to publish posts with their own connected social accounts (System User or OAuth, depending on the provider).
• One shared knowledge-base chat agent (Pattern 2) that answers product, billing, or onboarding questions across all customers, using sessionkey to keep each user's chat separate.

The two agents are independent deployments with different useragentguid values. Route user actions to the per-customer instance, and chat questions to the shared instance. Your backend decides which agent handles each request.

Building Your Product

White-Label Chat

Build a fully branded chat experience with no Wiro UI visible to your users.

The deploy flow has three stages — Deploy, Setup (only when the agent needs third-party credentials), and Start:

1. Deploy an agent via POST /UserAgent/Deploy — returns useragents[0].guid and starts the instance in status: 6 (setup-required) or status: 0 (ready) depending on whether the template needs credentials.
2. Setup the credentials (only if the agent template requires them) via one or more POST /UserAgent/CredentialUpsert calls and the matching OAuth flows — see Agent Credentials & OAuth. Check setuprequired on the response: while it's true, the agent cannot start. Once all required credential slots are filled, setuprequired flips to false and status becomes 0. For Pattern 2 (knowledge-base / chat-only agents) there are no third-party credentials, so this stage is skipped and the agent is ready to start right after Deploy.
3. Start the agent with POST /UserAgent/Start — transitions through status: 3 (starting) → status: 4 (running).
4. Build your own chat UI.
5. Send messages via POST /UserAgent/Message/Send.
6. Stream responses in real-time via Agent WebSocket using the agenttoken.
7. Manage conversation history with POST /UserAgent/Message/History.

See Agent Overview for the full lifecycle state table (status: 0, 1, 3, 4, 5, 6).

# Deploy — prepaid + tier are required for API users (credits debit from your wallet)
curl -X POST "https://api.wiro.ai/v1/UserAgent/Deploy" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "agentguid": "agent-template-guid",
    "title": "Customer Support Bot",
    "useprepaid": true,
    "tier": "starter"
  }'

# Pattern 1 only — fill any missing credentials, then verify setuprequired flipped to false
curl -X POST "https://api.wiro.ai/v1/UserAgent/Detail" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "guid": "deployed-useragent-guid" }'

# Start the agent (skipped if Deploy already returned status: 4 for cheap chat-only templates)
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "guid": "deployed-useragent-guid" }'

# Send a message
curl -X POST "https://api.wiro.ai/v1/UserAgent/Message/Send" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "useragentguid": "deployed-useragent-guid",
    "message": "How do I reset my password?",
    "sessionkey": "user-456"
  }'

Generative Media Studio

A richer variant of white-label chat: the agent doesn't just reply with text — it generates images, video, or audio through Wiro AI models and streams them into a live activity feed beside the conversation. This is the pattern behind Wiro's own Studio. It layers the realtime socket on top of the Session-Per-User model.

Shape:

• One deployed agent that has the int-wiro-aimodels skill enabled, with its wiro credential set to your Wiro project key (see Agent Credentials). Media the agent generates is billed to that project's wallet.
• One sessionkey per end user (Pattern 2 above) — the same agent instance serves everyone; each user's chat and media history is isolated by session.
• A single WebSocket connection carries three things at once: the streaming chat reply, the per-turn token-usage report, and discovery of any model runs the agent launches.

End-to-end sequence an integrator replicates:

1. Deploy once (prepaid) — POST /UserAgent/Deploy with useprepaid: true + tier. Set the wiro credential with POST /UserAgent/CredentialUpsert, then Start.
2. Open the socket — connect to wss://socket.wiro.ai/v1 and wait for the connected frame.
3. (Optional) name the session — POST /UserAgent/Message/RenameSession seeds a titled, empty session that shows up immediately in Message/Sessions.
4. Subscribe to run discovery — send { "type": "agent_info", "agenttoken": "<sessionkey>" } so you receive agent_wiroai_runtask frames for this session.
5. Send a message — POST /UserAgent/Message/Send with the user's sessionkey. Subscribe { "type": "agent_info", "agenttoken": "<agenttoken-from-send>" } and stream agent_start → agent_output × N → agent_end.
6. Patch token usage — ~250–500 ms after agent_end, an agent_usage_report frame delivers the turn's token counts, tokencost, and remainingcredits; splice them onto the message by messageguid.
7. Collect generated media — when the agent runs a model, an agent_wiroai_runtask frame arrives on the session channel with a socketaccesstoken. Subscribe to it with { "type": "task_info", "tasktoken": "<socketaccesstoken>" } and stream task_queue → task_start → task_output → task_postprocess_end; the final frame carries the output media URLs. See Agent WebSocket → Model runs the agent triggers.
8. Manage sessions — list with Message/Sessions, rename with Message/RenameSession, clear/forget with Message/DeleteSession (rotate: true to wipe the agent's memory of the thread).

Either deployment shape works: run one media agent and separate users by sessionkey, or deploy separate agents per workspace/customer — both use the exact same socket and messaging surface.

Webhook-Driven Pipelines

For backend-to-backend integrations where you don't need real-time streaming.

1. Send a message with a callbackurl
2. Continue processing other work
3. Receive the agent's response via HTTP POST to your webhook endpoint
4. Chain the result into your next workflow step

See Agent Webhooks for payload format and retry policy.

curl -X POST "https://api.wiro.ai/v1/UserAgent/Message/Send" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "useragentguid": "deployed-useragent-guid",
    "message": "Generate a weekly performance report",
    "sessionkey": "pipeline-run-789",
    "callbackurl": "https://your-server.com/webhooks/report-ready"
  }'

Scheduled Automation

Combine agents with cron jobs for recurring tasks.

Cron (every Monday 9am)
  → POST /UserAgent/Message/Send (with callbackurl)
    → Agent processes the task
      → Webhook fires to your server
        → Your server emails the report / posts to Slack / updates dashboard

This pattern works well for weekly social media content planning, daily ad performance reviews, monthly newsletter generation, and automated lead enrichment pipelines.

Multi-Agent Orchestration

Deploy multiple specialized agents and coordinate them from your backend.

Your Backend
  ├── Research Agent → "Find trending topics in AI this week"
  │     ↓ webhook response
  ├── Writing Agent → "Write a blog post about: {research results}"
  │     ↓ webhook response
  └── Publishing Agent → "Publish this post to WordPress and share on social media"

Each agent is an independent instance with its own credentials. Your backend passes output from one agent as input to the next.

Available Agents

Wiro provides pre-built agent templates you can deploy immediately. Each agent specializes in a specific domain and comes with the relevant skills and credential slots pre-configured.

The list above matches the agent templates currently deployed in production. The exact set evolves over time as new templates ship — fetch POST /Agent/List for the live catalog. Each agent's full marketing page lives at https://wiro.ai/agents/{slug} (linked in the first column).

Deploying an Agent

import requests

headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

# List available agents
agents = requests.post(
    "https://api.wiro.ai/v1/Agent/List",
    headers=headers,
    json={}
)
print(agents.json())

# Deploy an instance (API users always use prepaid — credits debit from your wallet)
deploy = requests.post(
    "https://api.wiro.ai/v1/UserAgent/Deploy",
    headers=headers,
    json={
        "agentguid": "social-manager-agent-guid",
        "title": "Acme Corp Social Media",
        "useprepaid": True,
        "tier": "starter"
    }
)
useragent_guid = deploy.json()["useragents"][0]["guid"]

# Connect Twitter via OAuth
connect = requests.post(
    "https://api.wiro.ai/v1/UserAgentOAuth/OAuthConnect",
    headers=headers,
    json={
        "useragentguid": useragent_guid,
        "credentialkey": "twitter",
        "redirecturl": "https://your-app.com/settings?connected=twitter"
    }
)
authorize_url = connect.json()["authorizeUrl"]

# Start the agent
requests.post(
    "https://api.wiro.ai/v1/UserAgent/Start",
    headers=headers,
    json={"guid": useragent_guid}
)

# Send a message
message = requests.post(
    "https://api.wiro.ai/v1/UserAgent/Message/Send",
    headers=headers,
    json={
        "useragentguid": useragent_guid,
        "message": "Create a thread about our new product launch",
        "sessionkey": "campaign-q2"
    }
)
print(message.json())

Browse available agents and their capabilities via POST /Agent/List or in the Wiro dashboard.