docs(skill): document ctx.input, drop daemon teaching, prune platform-tool prose#22
Merged
Merged
Conversation
…-tool prose - api.md: add ctx.input section with AgentInput method signatures (get/require/artifact_refs/artifact_json) and InputArtifactRef; fill in previously-missing public exports (AgentInput, SkillDefinition, Http, Llm, Tools, SessionData, ToolDefinition, AgentExtras, ArtifactRef, OutlineRef); describe output_schema and use_workspace_skills semantics; add skills field and SkillDefinition block to AgentContext. - examples.md: new Tier 6 covering upstream-step output consumption via ctx.input.get / ctx.input.artifact_json, with the workspace.yml FSM wiring that populates it. - SKILL.md: replace the "register via the daemon HTTP API" block with a workspace-integration section that points to platform tooling and keeps only the workspace.yml snippet. Remove request_human_input / save_memory_entry sections — platform-tool guidance belongs in the host platform's own skill, not the SDK skill. Consolidate the input-handling intro into a signal-payload-vs-inputFrom table for clearer model steering. - constraints.md: drop the "atlas agent register" build-pipeline section so the skill no longer teaches daemon plumbing.
…v var Review found two factual errors in the prior commits: - output_schema/input_schema decorator kwargs were documented as dataclass-to-JSON-Schema conversion that ships to the host. The bridge never assigns the *_json_schema registry fields, so the dataclass is silently dropped — the feature is unimplemented. Drop the schema-extraction narrative from api.md and constraints.md; mention both kwargs are accepted but no-op today. Re-describe ctx.output_schema as host-driven (sourced from raw["output_schema"] on the execute payload), since that is what the runtime actually populates. - SKILL.md claimed the host sets FRIDAY_NATS_URL; the SDK reads NATS_URL (_bridge.py and tests). Fixed. Also: tighten Tier 6 dict guard to isinstance(payload, dict) so the example doesn't TypeError on non-container payloads; add __version__ to Public Exports list; add a one-line note explaining where AgentInput.raw comes from (the host's execute payload).
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
1 participant
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.
Summary
Sharpens the
writing-friday-python-agentsskill so it teaches authoring well and stops at the SDK boundary.ctx.inputis now documented inreferences/api.md. Previously SKILL.md teased it as a first-class capability (the v0.1.8 feature) but the API reference had no## ctx.inputsection. All fourAgentInputmethods are now spelled out, plusInputArtifactRef. Also filled in the previously-missing public exports (AgentInput,SkillDefinition,Http,Llm,Tools,SessionData,ToolDefinition,AgentExtras,ArtifactRef,OutlineRef).inputFromconsumption showing the workspace.yml FSM wiring plus the consumeragent.pyusingctx.input.getwith anartifact_jsonfallback. Closes the gap where models knew the API existed but had no end-to-end pattern to mimic.curl http://localhost:8080/api/agents/register) and the "Test directly" curl examples are out. Replaced with a "Getting Agents Into a Workspace" section that points at the host platform's own tooling and keeps only theworkspace.ymlsnippet. The "atlas agent register" build-pipeline section is gone fromconstraints.md. The SDK shouldn't be telling agents how to talk to a daemon, and the hardcodedlocalhost:8080was wrong for any TLS-enabled install anyway.output_schemaanduse_workspace_skills. Both decorator params were listed without semantics inapi.md; now each has a short section explaining what surfaces at runtime (ctx.output_schema,ctx.skills).request_human_inputandsave_memory_entry/list_memory_entriessections are gone — those tools come from the host platform, not the SDK, and platform-tool guidance lives in the host platform's own skill. Replaced with a one-paragraph "Platform-injected tools" pointer reminding callers toctx.tools.list()and check platform docs.promptvs upstream-step output viactx.input) so the model can navigate by use case instead of by SDK surface.Test plan
SKILL.mdand the three reference files — confirm headings line up with their tables of contents.grep -r "localhost:8080\|localhost:5200\|FRIDAYD_URL\|/api/agents/register\|atlas agent register" packages/python/skills/writing-friday-python-agents/returns nothing.ctx.inputsignatures matchfriday_agent_sdk/_types.py::AgentInput.inputFromsemantics.