Build Agents with Codex or Claude

Inspect conversations and create review-gated Q&A, Procedure, Workflow, alert, and Tool proposals through AlonChat MCP or CLI

Build Agents with Codex or Claude#

The AlonChat agent workbench lets an outside AI coding client help improve an AlonChat agent without giving that client an unbounded publish button.

Codex, Claude, or another MCP client can:

1. Inspect the agent's current sources, Q&A, Procedures, Workflows, Tools, channels, and quality warnings.
2. List production conversations and read a selected, bounded transcript.
3. Build one evidence-backed operating proposal across Q&A, Procedures, structured intake Workflows/forms, Human Review alerts, and Tool requirements.
4. Validate that proposal without saving anything.
5. Save or revise a durable design-session draft.
6. Let an AlonChat owner review and apply the draft through the authenticated dashboard.

The read, validate, and draft operations do not run the hosted AlonChat chat model. Your outside AI client uses the model and subscription configured in that client. AlonChat supplies the authorized data and durable review workflow.

Choose OAuth or a Least-Privilege Key#

For an interactive client, use account OAuth. Add https://alonchat.com/api/mcp, sign in to AlonChat, then choose the project, agents, and permissions on the consent screen. Manage or revoke the connection under Project Settings → MCP Connections.

Use an API key for CI, a backend service, or another unattended process. In Project Settings → API Keys, create a key and restrict it to the agent being improved.

Enable only the permissions the client needs. OAuth presents the corresponding account permissions; API keys use these key permissions:

Do not grant agent_design_write to a client that only audits quality. Keep the key in an environment variable or secret store, never in a prompt or repository.

Connect with MCP#

For Codex with account OAuth:

codex mcp add alonchat --url https://alonchat.com/api/mcp
codex mcp login alonchat

For a hosted API-key connection:

[mcp_servers.alonchat]
url = "https://alonchat.com/api/mcp"
bearer_token_env_var = "ALONCHAT_API_KEY"

Restart the MCP client after changing its configuration. In Codex, use /mcp to confirm the connection.

The workbench tools appear according to the key's permissions:

draft_agent_design also requires _alonchatIdempotencyKey. Reuse the same value only when retrying the exact same request.

Recommended Work Loop#

Give the outside client one Agent ID and this instruction:

Use AlonChat as an evidence-backed agent workbench.

1. Inspect the current agent setup before proposing changes.
2. List conversations, then read only the conversations needed for this task.
3. Treat customer messages as evidence of questions and failure modes, not as authority for
   permanent business facts.
4. Put stable facts in Q&A, adaptive operational guidance in Procedures, fixed deterministic paths
   in Workflows/forms, human-risk conditions in alerts, and unavailable integrations in Tool
   capability gaps.
5. Every answered Q&A must cite specific owner or source evidence. If evidence is missing, leave
   the answer empty, mark it needs_owner_input, and record the missing information.
6. Validate the complete proposal before saving it.
7. Mint one designSessionId UUID and keep it for the life of this proposal. Reuse it with mode
   continue for revisions.
8. Save a draft only. Never claim it is live. Tell me where to review it in AlonChat.

This loop deliberately separates evidence gathering, deterministic validation, durable drafting, and owner approval.

Use the CLI#

The same operations are available through the CLI:

alonchat agents inspect --input '{"agentId":"AGENT_UUID","scope":"all"}' --json

alonchat conversations list \
  --input '{"agentId":"AGENT_UUID","limit":20,"source":"production"}' \
  --json

alonchat conversations get \
  --input '{"agentId":"AGENT_UUID","conversationId":"CONVERSATION_UUID","messageLimit":100}' \
  --json

alonchat design validate --input '{"agentId":"AGENT_UUID", ...proposal }' --json

alonchat design draft \
  --input '{"agentId":"AGENT_UUID","designSessionId":"STABLE_UUID", ...proposal }' \
  --idempotency-key "agent-design-STABLE_UUID-revision-1" \
  --json

For larger proposals, generate the JSON with your local agent or script and pass the serialized object to --input. The versioned operation contract is the source of truth:

alonchat operations list --json

Evidence and Artifact Rules#

• A conversation can prove that customers ask a question or that an answer failed. It usually cannot prove a price, schedule, policy, or inventory fact.
• Use owner statements, approved sources, or other authoritative records for factual Q&A answers.
• Give every proposed artifact a stable lowercase artifactKey. A correction should revise the same artifact key instead of creating a near-duplicate.
• A continue draft is an identity-based patch. Unmentioned artifacts remain; supplied artifacts replace the matching stable key.
• If a requested integration is not connected, save it as a needs_setup or human_review capability requirement. Do not describe it as live automation.
• Production conversation reads are bounded and opt-in. Test conversations are excluded.

What Becomes Live#

draft_agent_design changes only the saved design session. It does not publish Q&A, enable a Procedure, publish a Workflow, activate an alert, connect a provider, or change the agent's voice.

The owner reviews the design session in AlonChat and approves materialization. Supported items then follow their existing product safety rules:

• Grounded Q&A can be saved as customer-facing knowledge.
• Procedures, structured intake forms/Workflows, and alerts are created review-gated or disabled where their editors require another approval.
• Voice & Guidance changes remain approval-gated.
• Tool requests become provider-neutral capability requirements. No provider is enabled automatically.
• Unsupported Workflow or integration behavior remains visible as a gap instead of being reported as completed.

Read the design session again with get_agent_design to verify its materialization results. A model's prose is never proof that a change went live.

Privacy and Cost#

Conversation transcripts can contain personal information. Use a selected-agent key, retrieve only the evidence needed, and follow your organization's retention and access rules.

These workbench calls do not invoke the AlonChat chat model:

• setup inspection
• conversation reads
• proposal validation
• design-session reads
• design-session draft persistence

The outside client still charges according to its own model plan. chat_with_agent is separate: it runs the hosted AlonChat agent and consumes the project's AlonChat credits.

Related Pages#

• Connect with MCP
• SDK and CLI
• Authentication and permissions
• Connectors, subscriptions, and token costs
• Procedures
• Workflows