Author and publish a managed agent

An agent is one Markdown document. Optional YAML frontmatter holds settings, and the body holds instructions and resource mentions.

The server is the only parser and compiler. CLI, SDK, and Studio send the exact document. Do not calculate a digest or rebuild the document from a parsed object.

You save a document as a draft revision, validate it, and optionally test it. You then review its diff and access, and publish it with Go live. The Live version is what invocations and schedules use.

Start with the no-connection support example below. Shared app and MCP connections are available when configured for your project. Shared secrets require the managed sandbox secrets capability. Test saved drafts in Studio before publishing. Signed-in users can connect personal accounts. Agent schedules follow the Live version at each occurrence.

Install the authoring skill

Download the authoring skill into your coding agent’s skill directory. For a project-local Codex installation:

mkdir -p .agents/skills/author-sikaru-agent
curl --fail --output .agents/skills/author-sikaru-agent/SKILL.md \
  https://sikaru.ai/skills/author-sikaru-agent/SKILL.md

The frontmatter JSON Schema validates the parsed YAML object, not the entire Markdown file. Server validation also checks resource availability, matching mentions, model choices, project ceilings, and the combined 100,000-character instruction limit.

Create your first agent with the CLI

Install the Sikaru CLI using the current CLI guide. Have jq, a real project ID, and a server-side SIKARU_API_KEY available. The key needs managed-agent write access and the run permissions required for invocation.

curl --fail --output agent.md https://sikaru.ai/examples/agents/support.md
export PROJECT_ID='your-real-project-id'

jq -n --rawfile document agent.md \
  '{agentSlug:"support",displayName:"Support",source:{sourceKind:"agent_document",document:$document}}' \
  | sikaru managed-agents create_managed_agent --project-id "$PROJECT_ID" --json -

sikaru agents pull --project "$PROJECT_ID" --agent support --file agent.md
sikaru agents validate --project "$PROJECT_ID" --agent support --file agent.md

sikaru agents review --project "$PROJECT_ID" --agent support --revision 1 > review.json
# Inspect review.json and obtain authorization before publishing.
sikaru agents publish --project "$PROJECT_ID" --agent support \
  --revision 1 --access-digest "$(jq -r .accessDigest review.json)" --acknowledge-widening
sikaru agents snippets --project "$PROJECT_ID" --agent support

Built-ins are enabled by default except settings explicitly disabled in the document. The first publication acknowledges those capabilities as well as named connections. For later publication, pass the current --live-version VERSION_ID, current revision, reviewed access digest, and the acknowledgements warranted by the reviewed delta.

Use the public document review API (POST /v1/projects/{project_id}/managed-agents/{agent_slug}/document/review) to inspect the diff before a change. Its publication schema accepts expectedAccessDigest to bind publication to that exact review.

Worked documents

These examples are structurally valid. The app and MCP examples also require matching shared project connections and available tools before publication. Use the actual resource slug from Connections, not a display name guessed from prose.

Support: no connections required

---
budget:
  max_calls: 20
  max_tokens: 12000
tools:
  bash:
    enabled: false
---
# Support guide
Explain the policy supplied in the conversation. State what is missing before
making a recommendation. Ask before taking an external action.

Shared app: connect HubSpot first

---
access:
  "@app/hubspot":
    ownership: shared
    policy: require_approval
---
# Account brief
Use @app/hubspot to summarize the requested account. Cite the records you used.
Ask the user to review any proposed change before writing it.

Shared MCP: connect research with its search tool first

---
access:
  "@mcp/research":
    ownership: shared
    tools: [search]
    policy: allow
web:
  allow_domains: [example.com]
---
# Research assistant
Use @mcp/research to search the connected collection. Explain uncertainty and
cite the results. Do not invent documents that were not returned.

Mentions and access

Mention syntax is @app/slug, @mcp/slug, @secret/slug, @skill/slug, or @agent/slug.

• A slug starts with an ASCII letter or digit and continues with letters, digits, underscores, or hyphens.
• Resource names are case-sensitive.
• Mentions in fenced or inline code and escaped mentions do not grant access.
• A YAML access entry must have a matching body mention. Adding access in Studio inserts a mention; removing the mention removes access on publication.

Each access entry accepts these fields:

The validator reports each resource as resolved-shared, resolved-personal, unresolved, ambiguous, broken, or blocked. Unresolved, ambiguous, broken, and blocked resources need attention before Go live.

An intentional changed tool definition must be reviewed and explicitly acknowledged to pin the new definition. Revoked tools never silently fall back to another connection or search provider.

Built-ins are web search, web fetch, code execution (bash), workspace files (workspace), memory, and subagents (agents). All default on within project ceilings. Frontmatter also supports model, budget, web, setup, and embedded sources; consult the schema. The server refuses unknown keys. A schema pass alone is not permission to use a resource.

Save drafts, go live, and accept suggested changes

Saving a draft leaves live behavior unchanged. Go live publishes a new version. Removing or widening access requires explicit confirmation. Existing sessions keep their pinned instructions, but removed access stops on their next turn.

Versions record author and time. Review a diff before reverting and confirm the real revert operation. A stale save or publication is refused.

Evolve and Improvements may suggest prose changes. They cannot add or remove mentions or change access settings. Accepting a suggestion creates a labelled suggested draft. It never overwrites your draft and never goes live directly. Adopt or dismiss it, then review and publish through the same human Go live flow.

Shared conversations show messages and tool calls to project members; model reasoning is hidden and secrets are redacted. Once a session uses a personal connection or secret, its entire conversation is readable in full only by its runner. Other members see its status and usage.

A project-key request’s user_id is a caller label and does not authenticate a Sikaru user.

Use secrets and personal accounts

Create a shared or personal secret in Connections with a write-only value and exact allowed hosts, then mention its slug, for example @secret/apollo. Validation stays blocked if managed sandbox secrets are not configured. A local compute session receives no placeholders and reports that secrets need the managed sandbox.

In managed sandbox code, read the nonsecret placeholder by its exact slug:

import json
import os
import requests
placeholder = json.loads(os.environ["SIKARU_SECRET_PLACEHOLDERS"])["apollo"]
response = requests.get(
    "https://api.apollo.io/v1/example",
    headers={"Authorization": f"Bearer {placeholder}"},
    allow_redirects=False,
)
response.raise_for_status()

• The placeholder stays stable within a session, including after value rotation.
• Only request headers to currently allowed HTTPS hosts receive the real value.
• Other destinations are refused, redirects are not followed, and echoed values are redacted from response headers and streaming bodies.
• Body substitution is not supported.
• Removing a mention, revoking its connection, or narrowing hosts removes that reach from existing sessions too.
• A require_approval secret pauses each outbound request for its own decision in the ordinary pending-actions and approval APIs. Denying that request never reveals the value. Approval does not grant later requests.

Personal connections belong to each signed-in runner; missing accounts prompt the runner to connect and resume. Scheduled calls use the authority described below. Channels and inbound webhook triggers are outside this authoring flow.

Test a saved draft

In Studio, enter a Test message and choose Test current draft. Studio saves pending edits and pins that exact revision. Review and acknowledge any added or changed access.

• The test runs as the signed-in tester and appears in Conversations labelled Draft.
• It keeps memory and workspace files separate from Live.
• Testing never activates the candidate or changes existing Live instructions.
• Unresolved, broken, or ceiling-blocked mentions name the issue and refuse the test.
• Authorized project members share access to shared connection slots. Personal accounts resolve as the signed-in tester.
• A missing account pauses the turn so the tester can connect and resume. A project-key run fails that personal call with needs_signed_in_user and continues without borrowing an account.

From the public API, create an execution session with environment: "draft" and draft_revision set to the saved revision. Set acknowledge_widening: true only after reviewing its access changes. Pass the review’s accessDigest as expected_access_digest to refuse a changed tool or host snapshot. Project-key requests still require tenant_id and user_id; those labels do not authenticate a person. Then append a turn and read its events as for a Live session. A stale revision returns HTTP 409.

The separately installed authoring companion tests the same saved document:

sikaru-authoring dev support --project PROJECT_ID --revision 2 \
  --tenant customer-123 --user user-123 --prompt "What changed?"

Add --acknowledge-widening after reviewing added or changed access. dev accepts an existing agent slug and saved revision; it creates no temporary agent. Use the server document import operation to turn files into a document, then save that exact document through the revision-checked authoring workflow above. init and check keep their existing directory manifest interface.

Invoke the live agent

These examples are generated from the same source as Studio and agents snippets. Replace PROJECT_ID with your project. The agent slug here is support; fetch snippets for your actual agent after Go live. No example contains an API key.

: "${SIKARU_API_KEY:?Set SIKARU_API_KEY in your environment}"
SESSION=$(sikaru execution-sessions create --project-id PROJECT_ID --harness-id support --tenant-id customer --user-id user | jq -r '.session.id')
RUN=$(sikaru execution-sessions append_turn --project-id PROJECT_ID --session-id "$SESSION" --idempotency-key "$(uuidgen)" --input '{"message":"Hello"}' | jq -r '.run.id')
sikaru runs stream_events --project-id PROJECT_ID --run-id "$RUN"

Existing directory authors

The explicit sikaru.json file-tree manifest stays supported by the separately installed sikaru-authoring companion and Python sikaru_authoring.compile_directory. It packages only listed files and rejects symlinks, traversal, duplicates, and invalid definitions.

Use that existing contract for directory integrations. Do not pass a directory digest as an agent document. Document agents use the single-file workflow above. Legacy directory release changesets keep their existing review and staging/production operations; document suggestions require Go live.

Troubleshooting

Schedule the live agent

Create an agent schedule with POST /v1/projects/{project_id}/run-schedules:

{
  "agent_slug": "support",
  "environment": "production",
  "cron": "0 9 * * MON-FRI",
  "timezone": "America/Los_Angeles",
  "session_mode": "fresh",
  "input": {"goal": "Summarize today's work."},
  "idempotency_key": "support-weekday-summary"
}

Choose cron with an IANA timezone, or interval_seconds (60 through 2592000).

A running or not-yet-delivered previous occurrence causes a recorded overlap skip. Missed times coalesce into one occurrence, then the next future time is scheduled.

The Studio offers these same operations under Triggers.

A signed-in creator uses personal connections only when they published the current live version.

• A different publisher produces needs_schedule_owner_confirmation.
• A missing account produces personal_connection_missing.
• Those tool calls fail, the creator receives a notice, and the rest of the run continues.
• Project-key schedules never acquire a human identity or borrow the publisher’s account.
• Confirmed membership removal pauses a human creator’s schedule and records an administrator notice. An unavailable membership service defers admission.

Existing unsigned API schedules using session_id keep their pinned session contract. Sessions carrying a signed-in identity must use an agent_slug schedule so each occurrence receives current membership and personal-access checks. Retained identity-bearing session schedules pause with a notice instead of running.

Conversation channels

Managed agents can start with HTTP or a configured Slack room/personal DM. HTTP is the default for older creation clients. Slack setup lives in Settings → Channels; tool Connections stay separate. A channel never grants personal connection authority. Publication and explicit channel activation are separate actions.

Next steps