Build with a coding agent

Click Copy Prompt above and paste it into Codex, Claude Code, Cursor, or your coding assistant to carry out this workflow in your project. Start with the Building with AI overview for setup and access requirements.

Discover before creating

Use get_connection to inspect the credential's scopes and accessible workspace IDs. With workspaces:read, call list_workspaces; select a workspace explicitly. Call list_agents and get_agent before creating or changing an Agent. This avoids duplicate Agents and preserves existing configuration.

Agent definitions expose name, system_prompt, suggested_prompts, product_scope, and configuration. The nested configuration follows the existing SDK configuration schema, including its camelCase field names. Internal billing and runtime fields are excluded. Updates refresh the dashboard and deployed embed configuration.

Creation respects workspace capacity. Archive and restore require the workspace owner and agents:archive; restoring checks capacity again.

Add knowledge and integrations

Add a URL with the knowledge API or call create_knowledge_upload with file_name, content_type, and exact size_bytes. Upload bytes to the returned URL using its required headers only. The authorization expires after five minutes and is bound to the Agent and initiating credential. Retry that upload to receive the same document_id.

Inspect the document until its status is ready or failed. If extraction fails, inspect the error and fix the source before retrying. processing only means ingestion has been accepted.

For third-party MCP tools, discover the proposed server's tools, save the connection, then inspect error_message, status, and its discovered tool list. Mutations require the owner and mcp_servers:write; connection header values cannot be retrieved.

For webhooks, configure the endpoint, queue a test, then inspect the delivery status. Queuing a test is not successful delivery. Webhook access requires owner authorization and the relevant webhooks:read or webhooks:write permission.

Connect your application

Reuse an integration key already stored in your server environment. If a new key is needed, the workspace owner can authorize create_integration_key with both api_keys:create and auth_tokens:create. Supply a stable idempotency_key of 16–128 letters, digits, underscores, or hyphens. Retry with that same value after a lost response.

The created key has only auth_tokens:create and can connect any Agent in its workspace. Its secret is returned by creation and same-credential retries for 24 hours; the MCP cannot retrieve existing key secrets. Store it in a server-only environment variable without printing it or committing it.

Follow the quickstart for React/Next.js or the vanilla embed. Your server calls the existing browser-token endpoint through @heroui/agent/server, deriving the user's identity from your application's session. Browser tokens and workspace keys are different credentials.

Define client tools in application code with typed inputs and outputs. Do not move application-specific behavior into platform configuration or the installed skill. Read the current client-tool documentation before implementing handlers.

Verify the embedded experience

Run the application and open it in a browser. Send a message, invoke a client tool, and check that the expected application action occurs. Then retrieve its conversation, messages, and run through MCP. Check persisted status, tool outcomes, latency, and errors against what happened in the browser.

There is no new headless run API in this workflow. Runtime verification happens through the embedded app. Billing changes and workspace membership administration remain dashboard operations.

Diagnose failures