Agent Setup

AccessAgent’s AI agent is built on the OpenAI Agents JS SDK using SandboxAgent with UnixLocalSandboxClient.

How the agent works

Each project gets its own isolated agent sandbox:

1. When a user sends a message, the agent receives it along with the conversation history for that project session
2. The agent has read/write access to the project’s workspace directory (projects/{projectId}/)
3. The agent writes or modifies files in that directory
4. The center panel reloads the iframe, showing the updated widget
5. The agent’s response streams to the chat via SSE

Sessions persist in the database. When a user returns to a project, the agent resumes the conversation with full context — it knows which files it has written and what was discussed before.

Agent permissions

The agent can:

• Read, write, and edit any file inside projects/{projectId}/
• Execute limited commands scoped to the project directory

The agent cannot:

• Access files outside its project directory
• Make network calls from the server (widgets can make fetch calls from the browser)
• Access the database or other projects

Configuring the model

Set the AGENT_MODEL environment variable:

AGENT_MODEL=gpt-4o

Recommended models:

Model	Quality	Speed	Cost
gpt-4o	Best	Medium	Medium
gpt-4o-mini	Good	Fast	Low
o3-mini	Excellent for complex widgets	Slow	High

System instructions

The agent receives a system prompt that explains its role and constraints. You can customise this by setting AGENT_INSTRUCTIONS in your environment:

AGENT_INSTRUCTIONS="You are a widget builder for Acme Corp.
Always use our brand colours: #1a1a2e for backgrounds,
#e94560 for accents. Never include external fonts."

Tip

Use custom instructions to enforce brand guidelines, coding standards, or project-specific constraints that apply to all widgets your team builds.

Widget development guide

See Widget Development for guidance on what the agent can build and how to get the best results.