Connect your agent

Your agent uses its existing SDK against a local world. Worlds supplies the endpoint, credentials and task input for each run. Configure the agent once; each fresh test receives fresh connection settings.

In the dashboard, open a world and choose Connect. Create an agent profile there, or manage existing profiles under Settings → Agents. A profile records the command, working directory, timeout and connection options.

Choose the task format

The input depends on the workflow you are testing.

Native input uses tickets[].id for the connector's ticket ID and task_id for the suite's task ID. It does not include ticket text or expected outcomes. Native runs discard stdout and stderr; the grader reads world state. See Zendesk test files for that contract.

For a billing task, the wrapper can be as small as:

const task = JSON.parse(process.env.WORLDS_TASK_JSON);
const reply = await handleTicket(task); // your existing agent entry point
process.stdout.write(reply);

The command that runs this wrapper is your agent command. An agent behind HTTP needs a local wrapper that forwards both the task and the per-run connection settings. Its process must be able to reach the local world. An agent behind a queue needs a wrapper that submits the task and waits for completion.

Use the local connection settings

Read the values supplied for the current run. Do not hard-code an endpoint or reuse credentials from an earlier world.

The dashboard's Connect panel shows guidance for the selected connectors. Copy developer setup instructions includes binding placeholders and the invocation contract. It leaves out credentials, private task content and answer keys.

Source-account import credentials serve a different purpose: they copy starting data. Your agent should use the local credentials supplied for the test.

Stripe example

The CLI can configure a stock Stripe client automatically through the Node or Python startup environment. A client that sets its own host is left alone. Bundled applications and other SDKs may need explicit configuration:

import Stripe from "stripe";

const url = new URL(process.env.WORLDS_BASE_URL);
const stripe = new Stripe(process.env.WORLDS_API_KEY, {
  host: url.hostname,
  port: url.port,
  protocol: url.protocol.slice(0, -1),
});

import os
import stripe

stripe.api_key = os.environ["WORLDS_API_KEY"]
stripe.api_base = os.environ["WORLDS_BASE_URL"]

Use --no-preload or WORLDS_PRELOAD=0 when you configure the SDK yourself.

Check the connection

Use the dashboard's connection checks, then run one small test with a known expected outcome.

• HTTP checks confirm that the local API responds.
• Agent checks inspect traffic from your command. They use a temporary world. The Stripe check supplies a bundled task; native and combined checks do not supply a normal evaluation task. A native agent that waits for task input may produce no traffic during that check.
• A fresh test checks the full task-driven path, including the expected record changes.

If there is no traffic, check the command's working directory, environment and SDK endpoint. If requests reach the world but fail, inspect the request log and connector scope. No record change can also be a correct outcome, so judge it against the task's expectations.

For the billing CLI workflow:

Native and combined workflows use the connector-aware diagnostics described in Zendesk test files.

Save the configuration

Agent profiles can reference a private environment file for model-provider keys and other secrets. Keep that file out of source control. The selected agent can use its own model provider; Worlds does not change the agent's model configuration.

Continue with tasks and expected outcomes, or follow the dashboard workflow to create and run a suite.