Quickstart

New accounts start with identity creation. To create another, choose Create agent identity from your dashboard; account limits apply.

Give your agent an identity and activate its email Inbox. You can connect the code you already run when ready. Outbound sending currently requires reviewed pilot setup; enabled Free accounts have a 10-recipient daily limit. Add a phone number and connect incoming calls to your voice agent. Your voice system handles the conversation; messaging remains preview.

1. Sign in

Open AgentOwl. Choose Sign in with Google, or enter your email address and choose Send verification code. For email sign-in, enter the six-digit code sent to that address within 10 minutes. The code can be used once. A first successful sign-in creates your account and opens Create your agent identity. If an existing Google account says to use its original sign-in method, sign in with Google and enable email login in Settings before using codes for that account.

2. Choose the agent's capabilities

AgentOwl suggests a random agent name and identity ID. Keep the suggestion, edit the name, or choose Suggest another name.

Select at least one capability:

• Email — receive email at <email-name>@<identity-id>.agentowl.dev. Free supports up to three email addresses; this flow starts with one.
• Phone calls — receive incoming calls on an assigned number and connect them to your voice agent.
• Messaging — receive SMS and MMS on that number.

The agent card preview updates as you edit the name and choose channels. Email name is suggested from your agent name and can be edited before creation.

Phone calls and messaging share one number when both are selected. Selecting them records what you want; it does not provision a number or take payment.

Choose Continue to open the details page. If phone or messaging is selected, the channel cards show paid setup details and the price before continuing. On the next page, enter a preferred US area code (optional) and describe the intended use. Preferences are saved for reference; they do not reserve a number or approve messaging.

If the agent represents an organization, select Add an organization (optional) and enter its name. Otherwise the agent's own name is used. Under Customize identity address, you can change the suggested ID before creation. It cannot be changed afterward. For free receiving, select Email so you can activate the Inbox. Select Phone calls to save your voice setup preferences.

Click Create agent identity. You now see your agent's name, selected capabilities, and the steps to activate email or connect a runtime. Its workspace remains the isolation boundary used by the API and CLI.

3. Add voice

For incoming calls, set up voice in Admin. With an active paid plan, choose an eligible number, configure your SIP destination, publish the workspace route and check your funded call limits before activation. Your account shows which setup actions are available; contact support@agentowl.dev if setup is unavailable for your account. The voice guide explains the handoff; the pricing page shows the published call-leg and transfer rates. SMS and MMS are in preview and require separate registration.

Your account shows whether self-service purchase is available; viewing the review does not charge you. You can continue using Free email while you set up voice.

After Pro is active, use Choose or check your number to select a number and follow provisioning. An available number, active calling, and approved outbound messaging are separate states. You can connect free email while phone setup is pending.

4. Activate your email Inbox

If you selected Email, click Activate email Inbox on the Overview page. AgentOwl creates the address and starts receiving mail without a webhook. Send a message to the displayed address and open Inbox to inspect it. The Inbox does not run your agent. Messages received before a runtime is connected remain in the Inbox and are not automatically replayed to that runtime.

You can also connect a runtime directly. That creates and activates the address as part of the connection.

5. Request sending if needed

The current Free release is for receiving email. If you need outbound sending, contact support for reviewed pilot availability. An enabled account can use Send email on Overview to set up its AgentOwl address and check its status. Do not treat the address as ready to send until the panel says Ready to send.

Once sending is enabled, use Compose email to send a one-to-one test message to an address you control. Send history distinguishes a recorded request from acceptance by the receiving mail service; it cannot confirm Inbox placement. Check the recipient's Inbox and Spam folder, then reply and confirm the answer appears in your AgentOwl Inbox. Enabled Free accounts allow 10 recipient submissions per account per UTC day, with up to five new recipients in a rolling minute. The daily allowance resets at 00:00 UTC.

If your account is enabled for sending, open Connect an agent to send email and create a key for that exact address. Copy it into your runtime's secret store; it is displayed only once. The email domain and sending guide explains the API and reviewed setup for your own domain.

6. Connect your runtime when ready

Under Connect your runtime, enter a public HTTPS Runtime webhook URL, then click Connect runtime.

AgentOwl creates the runtime endpoint and routes, publishes the configuration, and activates the selected email address if needed. New messages go to the runtime after it is connected. If a step fails, Resume connection reuses the saved resources. After a phone number becomes available, resume connection to attach its events too.

Your receiver needs to durably store the event before returning 2xx, then run your agent in a background worker. Delivery acceptance and agent completion are separate.

The dashboard includes a runnable Python receiver setup. The durable receiver guide supplies the complete example with signature verification, SQLite storage, and duplicate acceptance protection. Python 3.10+ is the only dependency. A local receiver needs your own HTTPS tunnel or deployment before hosted AgentOwl can reach it.

Use Set up authenticated delivery to generate a signing secret. Install the secret and the displayed endpoint ID in the receiver, then activate signing. Save credentials in your runtime's server-side secret store.

The example worker processes messages locally. Replace it with your agent's code; it does not run a model or send replies for you.

7. Verify a real message

Once delivery is configured, Test your agent shows tests for its available selected channels:

• Email: copy the test code into an email subject, send to the displayed address, then click I've sent the test email. Open your email app fills in the address and subject.
• Messaging: send the displayed test code to the number, then click I've sent the test message.
• Phone calls: call the number after opening the test, leave a voicemail, then click I've made the test call. A webhook receiver gets call events; a live voice conversation requires a separate voice runtime.

AgentOwl checks for about 20 seconds. Email and SMS tests must contain the displayed code. A successful test requires a new event for the selected binding and channel, with a successful delivery to the selected runtime. Another address's message or another runtime's delivery cannot complete this test.

Open Inbox to inspect content and delivery errors. If the test has not arrived, check the receiver and try checking again. The test code remains the same while this setup view stays open.

8. Add progress and approvals

Basic delivery works without runtime callbacks. To report acceptance, progress, questions, approvals, and outcomes:

1. Follow Connect an agent runtime to implement the callback protocol.
2. Open Optional: progress and approvals, then choose Generate runtime token. Store this token in the runtime; it is shown only in the current view.
3. Once the runtime implements callbacks and has the token installed, select the confirmation checkbox and choose Enable work reporting.

Operator API keys manage configuration; runtime tokens report work and retrieve authorized content. Your runtime decides which actions require approval and enforces each decision before acting. Review results under Agent work and requests under Needs attention.

Test outgoing communications

For a connected messaging number, Send a test text from your agent uses the existing funded messaging API. Enter a number you control, review the usage-charge notice, and submit once. A recorded or submitted request does not confirm receipt; check your phone and reply to verify the incoming path. Unavailable live messaging or registration is shown as an error without enabling those features.

For a reviewed email-sending pilot, use the enabled address and the exact-address agent key from step 5. Send to an address you control, then reply to check both directions. If you use your own domain or an existing SMTP integration, follow email domain and sending setup. Outbound messaging requires an eligible number, approved registration, sufficient funds, and released live messaging support. Live voice audio uses a separate connection from the event webhook.

CLI and API

Existing CLI and API setup remains supported. A workspace is a tenant in those interfaces. See CLI setup and Event format. Operator API keys are available under Settings → API Keys.