Repository navigation
Conversation
…ory format Parse reads a directory from the files a client sent: agent.yaml, instructions.md, guardrail.md, skills, knowledge, knowledge/urls.yaml, simulations and the UI files agent.yaml names. It decides which of the files are the directory, so every client's send of one folder reads and hashes the same. Unknown and retired keys and wrong types are refused, every problem at once, each with its file, line and column. Render writes a directory back as canonical files a sync reads again, and says what it could not write. The grammar and the ui: compiler are the Go SDK's, ported with its tests and the JavaScript SDK's refusals.
POST /v1/agents/sync/files takes the files of an agent's folder and
reads them with agentdir, so every client's directory means the same
thing. A directory that does not read is a 400 invalid_agent_directory
whose problems name the file, line and column of each: what does not
parse, what the schema refuses and what the router cannot run, together
and bounded. The router finds a connector's connection among the app's
own by id or label, keeps the left-out behaviour, compiles ui: into
ui_instructions and takes the hash from the files it used. What a
program sets in code beside the directory goes in the same request and
wins over the files. dry_run answers what would be stored, refuses what
the sync would, the money for its knowledge included, and writes
nothing. It shares its implementation with POST /v1/agents/sync, whose
request is unchanged.
GET /v1/agents/configs/{id}/directory writes a stored agent back as its
canonical files, with what a directory cannot say in not_exported.
agent_configs.ui_source keeps what ui_instructions was compiled from
until somebody writes others, so the ui key and its files are exported.
A sync checks everything a write would refuse before the first write,
two skills of one name included. Its answer lists the skills, knowledge
documents, knowledge urls and simulations it creates, updates or deletes
as changes, and an unsynced_changes refusal carries what it would write
over as conflicts, with the last_change to send back as base_change.
…reads Sync reads the files the format names when it syncs, and no other file of the folder, and sends them to POST /v1/agents/sync/files with what the code set beside the directory, which still wins: the instructions, the guardrail, the harness's subagent, sandbox and skills, and the cost tracking labels. The router decides what agent.yaml means and which connections it names. Load still parses the directory for the program holding it. A link out of the directory is refused, what is not a regular file of text is left behind, and a directory over what a sync sends is refused by name. .agent_sync keeps a hash of what was sent and the sync_hash the router stored it under, in the format the JavaScript SDK writes, and a sync is skipped only while the stored config still has that hash and left no connector out.
…reads sync reads the files the format names when it syncs, and no other file of the folder, and sends a folder from loadFolder to POST /v1/agents/sync/files with what the code set beside it, which still wins: instructions, guardrail, harness, skills, the pipeline's models and the cost labels. The router reads the files, finds the connections and compiles ui:. loadFolder still parses the directory for the program holding it. A directory over what a sync sends is refused by name. .agent_sync keeps a hash of what was sent and the sync_hash the router stored it under, in the format the Go SDK writes, and a sync is skipped only while the stored config still has that hash and left no connector out. A folder built by hand without files, and an agent written in code, sync as before.
The sdk skill's note says what the other SDKs and the getstream CLI should do to send a directory's files; the generative-ui and connectors skills say where ui: is compiled and connections are found for a sync of files. Removing the SDKs' own parsers is AI-3441.
POST /v1/agents/sync/files and GET /v1/agents/configs/{id}/directory, the
changes a sync answers with, and the problems, conflicts and last_change
an error carries, as each SDK's generator writes them. Generated files
only.
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Linear: AI-3439. Dashboard counterpart: GetStream/volt-dashboard#1337 (AI-3440). Follow-up for the CLI and the other SDKs: AI-3441.
Why
An agent kept in a repository is a directory:
agent.yaml,instructions.md,guardrail.md,skills/,knowledge/,simulations/andui/. Until now, every client read that directory itself and sent the router fields it had mapped. The Go SDK, the JS SDK, the CLI and the other SDKs each have their own parser. They drift: the JS parser already refuses keys the Go one accepts, and the CLI has a third parser. The dashboard couldn't read or write the format at all without becoming one more parser.This makes the router the reader and writer of the format. A client sends the directory's files as they are. The router parses them, validates them against the schema and stores the result, and it can hand an agent's directory back. There is one set of rules and one set of error messages, and the CLI, the SDKs and the dashboard can all sync the same way.
flowchart LR subgraph before["Before"] direction LR G1[Go SDK parser] --> M1["POST /v1/agents/sync<br/>mapped fields"] J1[JS SDK parser] --> M1 C1[CLI parser] --> M1 end subgraph after["After"] direction LR G2[Go SDK] -->|files| F["POST /v1/agents/sync/files"] J2[JS SDK] -->|files| F D2[Dashboard] -->|files| F F --> A[agentdir<br/>parse · validate] A --> S[(config)] S --> R[agentdir<br/>render] --> E["GET /v1/agents/configs/{id}/directory"] endWhat it adds
POST /v1/agents/sync/files: sync a directory from its files{ "name": "front-desk", // optional when agent.yaml names it "files": [ // at most 1024 { "path": "agent.yaml", "content": "name: front-desk\nllm: openai/gpt-5.6\n..." }, { "path": "instructions.md", "content": "You answer the phone for ..." }, { "path": "skills/booking/SKILL.md", "content": "---\nname: booking\n..." } ], "dry_run": true, // answer with what it would store and change; write nothing "check_changes": true, // 409 unsynced_changes if the dashboard edited it since the last sync "base_change": "…" // go ahead over those edits }SyncAgentResultas/v1/agents/sync, pluschanges: the skills, knowledge documents, knowledge URLs and simulations the sync creates, updates or deletes ([{resource_type, name, action}]). Dry runs return it too.instructions,guardrail,skills,harness,subagent,sandbox,tags,llm,stt,tts,sts,voice,greetingandvideo./v1/agents/sync, so connectors, left-out connectors, knowledge, simulations, warnings and conflicts behave the same.Schema validation at the router, with positions
The schema is checked at every level: unknown keys, retired keys and wrong types. Problems come back together, each with its file, line and column:
{ "error": { "type": "invalid_request", "code": "invalid_agent_directory", "message": "agent.yaml:3:1: \"voise\" is not something agent.yaml says; …", "problems": [ { "file": "agent.yaml", "line": 3, "column": 1, "message": "\"voise\" is not something agent.yaml says; name, description, mode, …, ui, app are" }, { "file": "agent.yaml", "line": 4, "column": 10, "message": "plugins: no longer read: plugins were replaced by connectors, so name the provider under connectors" }, { "file": "agent.yaml", "line": 6, "column": 3, "message": "greeting: \"txt\" is not something greeting says; text, mode are" } ] } }floor_controlon this router, channels, region and the like) are collected and located the same way.problemsholds at most 100 entries, andproblems_omittedcounts the rest.A 409
unsynced_changeson either sync route now says what the sync would write over:conflicts: [{resource_type, name, removed?}], plus alast_changeto send back asbase_change. Clients no longer have to parse the message.GET /v1/agents/configs/{id}/directory: the agent as filesIt returns
{name, files, not_exported}.not_exportedlists what the files can't express for this agent, such as a binding's timeout or policy, knowledge that isn't text, or files over the limits.agent.yamlkey (llm_fallbacks,review,episode_cards) are neither written nor touched by a sync.Package layout
acceleration/internal/agentdir:Parse,Hash(length-prefixed parts) and the limits (MaxFiles,MaxBytes, per-file and UI caps);agent.yamlgrammar;urls.yamland simulations;ui:compiler;Render.acceleration/internal/api/directory.go: turns the parsed files into a sync request, resolves connectors on the server by id or unique label (scoped to the tenant), runs the schema check, and serves the two operations.20270105090000_agent_config_ui_source.sql: a nullableagent_configs.ui_sourcecolumn, so an export can writeui:back.ui_instructionsis edited outside a files sync, so an export never reverts that edit.SDKs
/sync/files, along with the settings set in code, which win as before.agent.yaml,instructions.md,guardrail.md,skills/,knowledge/,simulations/,ui/, and the UI pathsagent.yamlnames.LoadandloadFolderfill and refuse exactly as on main, for code that reads them. The router is what validates and stores. Removing the SDK parsers is AI-3441..agent_synchas one format in both SDKs:{hash, sync_hash, synced_at}./v1/agents/syncuntil AI-3441.Not breaking
POST /v1/agents/syncandSyncAgentRequestare byte-identical in the spec, and the existingSyncSuitepasses unchanged. Published SDKs and the CLI keep working.ErrorDetailandSyncAgentResult./v1/agents/syncnow validates skills, sources and URLs before it writes anything, and refuses duplicate skill names up front. Before, it could fail partway through..agent_syncstamp causes one extra sync after upgrading. That sync writes nothing./sync/files, so the router has to ship first.Validation
go build ./...andgo vet ./...pass, andgo run ./cmd/openapileaves no diff.go test -tags integration -p 1passes for./internal/api(the whole package, including the spec staleness test),./internal/agentdir,./internal/storeand./internal/knowledge/urls.go vet ./...andgo vet -tags e2e .pass,go test -race ./...passes, andgo generateleaves no diff.npm testpasses 785/785, andnpm run types -- --checkreports the types in step with the spec.dart run tool/generate.dart.unchanged.not_exported.conflictsandchangesas the real sync.